Full text of "TRS-80 Manual: Model 2 Disk Operating System Reference Manual (19xx)(Tandy)"

See other formats

Radio /hacK

TRS- 80 Modelll

Disk Operating System
Reference Manual

A Description of the Operating System:
General Information, Operator Commands,

Technical Information

CUSTOM MANUFACTURED IN THE U.S.A. BY RADIO SHACK

£3

A DIVISION OF TANDY CORPORATION

Section

New Release Update

TRSDOS 2.0

This section pertains to the latest release of trsdos. It describes important

operations you should perform before beginning any specific application. It

also summarizes the changes and improvements contained in this version

of TRSDOS.

Before attempting to follow any operations given in this section, you should
read Section 1 . For details on programs or utilities mentioned, see the

specific entry for that subject (use the Index).

Important

Do not try to use 1. 1 or 1.2 diskettes when the system is running under 2.0;

do not try to use 2. diskettes when the system is running under 1.1/1. 2.

Either case could destroy the information on the diskette. 1.1/1.2 diskettes

must be converted to 2.0, as explained in this section.

New Customers:

Ignore the references to trsdos 1,1/1.2; these are for customers who are

upgrading to 2.0.

ODEL II TRSDOS

Important Disk Operations

In this section, we will outline some things you should do before you begin any
applications with TRSDOS:

1 . Initialize Some New Diskettes (FORMAT)

2. Duplicate the TRSDOS Diskette (BACKUP)

3. Make a Working Master (PURGE)

4. Upgrade Diskettes from Previous Versions (XFERSYS)

You will need to use several TRSDOS commands and utility programs . In this
section we will list them briefly. For details, see the full descriptions elsewhere in
this manual (use the Index).

1 . Initialize Some New Diskettes (FORMAT)

Before any diskette can be used, it must be initialized or "formatted' ' — the data
regions defined and labeled, and a table of contents or "directory" created.

The FORMAT utility program performs this function. We suggest you format several
diskettes now. You cannot perform the other operations listed in this section until
you have done this.

Start TRSDOS as explained in Chapter 1 , then type in a command like this:

FORMAT:*/

where d is one of the drives in your system .

The Computer will prompt you to mount the diskette for formatting.

If you are formatting in drive 0, you must remove the TRSDOS diskette and insert
the diskette to be formatted.

The resultant formatted diskette will have the name TRSDOS and password
PASSWORD. For diskettes that will contain TRSDOS, we suggest you use these
default values . For your data diskettes , use any diskette name (ID = name) and any
password (PW = password) .

See FORMAT for further details .

VERSION 2.0 UPDATE

2. Duplicate the TRSDOS 2.0 Diskette
(BACKUP)

Use your factory-release TRSDOS diskette for one purpose only — as an " original
master' ' . It should not be used for applications , only for creating a ' ' working
master' ' . You can then make changes to the working master to suit various
applications.

As an added precaution, keep the factory-release diskette write-protected.

Note: In the BACKUP dialog, the term "source diskette" refers to the diskette to be
duplicated; "destination diskette" refers to the diskette to contain the copy of the
original.

Under TRSDOS READY, type in the appropriate BACKUP command. We suggest the
following:

BACKUP TO destination

where destination is the drive containing the formatted diskette which will become
a TRSDOS diskette.

If destination = 0, TRSDOS will prompt you when to swap source and destination

diskettes.

When the backup process is complete, remove the original diskette. Keep it in a
safe place and don't use it unless you need to recreate the working master.

3 . Make a Working Master (PURGE)

The factory-release TRSDOS diskette contains a variety of non-essential files. These
non-essential files serve various purposes, including:

• Demonstration of programming techniques

• Modification of system input/output software

• Special features and functions

Now that your original TRSDOS diskette is safely set aside, you should create one or
more customized system diskettes to suit your needs. For a discussion of "full
system' ' , "minimum system" , and "data" diskettes, see Disk File
Requirements later in this section.

Determine what files you will need for day-to-day use. You may want to have
several different system diskettes — each with a different collection of system files.

If there are some files you don't want on any of your working diskettes, you may
delete them from the working master. If there are files you don't want in a particular
application, delete them from that diskette only.

To delete files, use the PURGE command.

MODEL II TRSDOS

STEPS FOR CREATING A WORKING MASTER (B)
AND A SPECIAL APPLICATION DISKETTE (C)

SPECIAL

APPLICATIONS

SYSTEM

Here are the files included on the factory release TRSDOS 2.0 Diskette:

SYSTEM/SYS

This file is required on all TRSDOS diskettes. Do not purge it if you wish to use the
diskette in drive 0.

SYSRES/SYS

This file is required on all full system diskettes, but not on minimum systems. (To
find definitions, use the Index. ) If you want to use the diskette to start TRSDOS, do
not purge this file.

BACKUP, PATCH, XFERSYS, FORMAT, TERMINAL,
MEMTEST, BASIC

These important system files should be kept on your working master. The purpose
of each file is listed elsewhere in this manual (see entries in the Index) . After you
understand the purpose of each file, you may elect to delete any or all of them for
specialized purposes .

VERSION 2.0 UPDATE

S YSTEM64 and S YSTEM32

Only one of these two is needed in your system. If you have a 64K RAM system, keep
SYSTEM64 and delete SYSTEM32; if you have a 32K RAM system, keep SYSTEM32 and
delete SYSTEM64.

We will refer to the remaining file as SYSTEM/7/?, nn - 32 or 64, depending on
which one you kept.

SYSTEM//// contains the high-memory routines for: HOST, SPOOL, SETCOM and all
serial I/O, DO and DEBUG. You should keep this file on your working master. If you
have an application which will not require any of the above-listed capabilities, you
may delete it.

HERZ50, LPII, PRTBKSP

These are DO-files which allow you to make specific changes or ' 'patches" to
system files. SeeHERZ50, LPII and PRTBKSP for descriptions. If you don't need to
make any of these changes, you may delete these files from your working master.
Or if you do need to make them, delete them after they are used.

DOCOMnn, BASCOM/m, COMSUB/m, EXDATMmi,
DATMnn (nn = 32 or 64)

These are demonstration programs and routines. See the descriptions elsewhere in
this manual (use the Index).

For each file , there is a 32K RAM and a 64K RAM version . You should keep the
version that matches your system's RAM size and delete the other.

These files are for demonstration and incidental purposes only. You may delete any
or all of them from your working master, depending upon your needs .
(Programmers should study how they work, to gain insights into techniques for
using TRSDOS.)

4, Upgrade Diskettes from Previous Versions
(XFERSYS)

This section applies only to customers who have been using a previous version of
TRSDOS. New customers may skip it.

All diskettes — ' ' system ' ' and ' ' data' ' — must be converted before they can be
used under TRSDOS 2.0. The XFERSYS utility program does this for you. Attempts to
use un-converted 1 .2 diskettes under 2.0 may destroy the information on the
diskettes.

See XFERSYS for the proper procedures to upgrading a diskette. Follow them
carefully!

MODEL II TRSDOS

Disk File Requirements

There are three general configurations of diskettes that may be used in the TRSDOS
system:

• Full system — The factory release copy of TRSDOS for use in drive 0.

• Minimum system — May be used in drive after initialization.

• Data — May only be used in drives 1 , 2 and 3 .

Full System'

This is a diskette which can be used to start (' 'bootstrap' ') the operating system and
perform all the library commands, utilities, and supervisor calls. The factory
release copy of TRSDOS is a full system.

The full system contains many files which will not be needed for day-to-day
applications — but which may come in handy every now and then . For this reason ,
you should always keep your factory release version of TRSDOS intact, and use a
backup copy as a working master.

Why and How of Full System Diskettes

If you have a Disk Expansion Unit, you will probably find it most convenient to
have a Full System Diskette in drive at all times . This will give you access to all of
the utilities and system functions without a disk swap being necessary. For most
applications, there is still plenty of room left on a full system diskette for program
storage and for small to medium sized data files . Larger data files may be stored on
data diskettes in the Disk Expansion Unit.

It is faster, by the way, to put different files or programs being accessed at the same
time on different drives since, in most cases, the drive seek time will be reduced.
On each drive, the read/write head will usually be closer to the desired location of
the file currently being accessed. Using CREATE before building the data file will
help insure that the file will be stored in a large block of contiguous storage on
diskette. This will also help speed up disk accesses.

The working master that you create will be a full system diskette. The original
master is also a full system diskette and both should be kept that way.

VERSION 2.0 UPDATE

r--

"Minimum System"

This is a diskette which cannot be used to start TRSDOS , but may be used after the
system is fully initialized. This diskette contains the minimum amount of system
files required for TRSDOS operation after initialization.

You may want to create a minimum system diskette for use in special applications
where space in drive is at a premium. You may use PURGE or XFERSYS to create a
minimum system.

Why and How of Minimum System Diskettes

If you don't have a Disk Expansion Unit, but still need extra disk space for storage
of large data or program files, you may need to create minimum system diskettes
for use . This kind of diskette has the minimum operating system programs on it for
processing, but may not be used for resetting or starting up. These diskettes may
only be used in drive after you have reset or started using a full system diskette.
The minimum system diskette will contain the following system programs:

SYSTEM/SYS

SYSTEMS (nn = 32 for 32K machines, 64 for 64K machines)

Note: If you do not plan to use DO, HOST, SPOOL, DEBUG, or serial I/O during the
execution of your application, you will not need SYSTEM 64 or SYSTEM 32 on your
minimum system diskette.

The technique for using a minimum system diskette is as follows:

1 . Initialize using your working master (which must be a full system diskette) .

2. Remove this diskette from drive and replace with the minimum system
diskette that you have created.

3 . Now you may start running your application which should be on the minimum
system diskette.

If your application requires more than one diskette for the storage of files or
programs, then each diskette used (with your one-drive system) should be a
minimum system. Your application should be written such that you only have files
open on the diskette that is currently in drive 0, and that when you need to swap
diskettes to get data (or programs) from another minimum system diskette, that you
close the open files, then do the swap, then open the file(s) that you need from the
other diskette.

You may also use minimum system diskettes in a multi-drive setup, but keep in
mind that you must start or reset with a full system diskette in all cases.

To Create a Minimum System Diskette

There are two ways to create a minimum system disk. The first is to start with a
copy of either your working master or any other full system disk and, from this,
purge off all of the modules except SYSTEM/SYS and SYSTEM64 (or SYSTEM32) . The

MODEL II TRSDOS

other way to create a minimum diskette is to use XFERSYS with the MIN option. This
will purge off all of the unnecessary modules and will also purge off SYSTEM64
(and/or SYSTEM 32) . If you plan to use DO, HOST, serial I/O, DEBUG, or SPOOL in
your application, then you should use the "manual ' ' method using PURGE.

"Data"

This is a diskette which does not have the minimum system file requirement, and
therefore may only be used in the external drives ( 1 , 2 and 3) . Such diskettes have a
maximum of space available for user files .

Why and How of Data Diskettes

If you have a Disk Expansion Unit, and you plan to run applications or programs
that require large data files, you will want to have available as much disk space as
possible for the storage of the file(s) or program(s). In this case, you will not need
any of the operating system programs on such a diskette . While this kind of diskette
may not be used at any time in drive 0, it will have the maximum space available for
data or program storage. An empty data diskette is created by FORMAT. You may
copy or write data or program files onto this kind of diskette in large , contiguous
blocks for fast accessing later.

VERSION 2.0 UPDATE

Changes to TRSDOS

New Library Commands

These are described fully in the new pages for Section 2.

Function

Library
Command

ANALYZE

DUAL
ECHO
HELP
HOST

MOVE
PRINT
RECEIVE

RESET

SCREEN

SPOOL

STATUS

Gives diskette allocation information organized
by track

Duplicates output to video and line printer

Begins echo of keyboard input to display

Helps with TRSDOS command syntax

Allows keyboard input from and video output to a
remote terminal via the serial interface

Copies multiple files and re-organizes a diskette

Prints any file in text format

Inputs Intel hex format data into RAM from the serial
interface

Resets TRSDOS (like pressing the RESET switch)

Copies Video Display screen contents to the printer

Saves printer output in a disk file for later printing; also
allows printing of spool file while other operations are
in progress

Displays current top of user memory and on/off status of
various TRSDOS functions

Advances printer to top of form

MODEL II TRSDOS

New Utilities and Special Programs

These are described fully in the new pages for Section 3 .

Name Function

LPn Modifies the TRSDOS printer driver for use with the

Radio Shack Line Printer II (Catalog Number
26-1154)

MEMTEST Checks out random access memory

PRTBKSP Modifies the TRSDOS printer driver for use with printers

capable of backspacing

Changes to 1.2 Commands and Utilities

The following have been changed:

AUTO
BACKUP
CLEAR
COPY

FORMAT
FORMS
FREE
I

TERMINAL

VERIFY

XFERSYS

DEBUG
DIR

KILL
SETCOM

For details, see the replacement pages for Section 2.

Other Changes

Keyaheads

TRSDOS allows keyaheads of up to 80 characters. This means you can type in the
next command while previous ones are being executed.

Note: A keyahead will not be displayed until TRSDOS or the application program is
ready to interpret it.

For example, type in these three lines, without waiting for TRSDOS READY after the
first command:

DIR { SYS} (ENTER)
TIME (ENTER)
FREE (ENTER)

Press (BREAK) to interrupt the operation currently in progress; if a keyahead line is
available, TRSDOS will begi n inter preting it. Press (HOLD) to pause the operation
currently in progress; press (HOLD) again to continue.

VERSION 2.0 UPDATE

/■*V

Wildcard

Certain library commands allow you to specify a collection of files by using a
"wild-card" field in place of the file name and/or extension. An asterisk ' '*" in a
file specification represents a wild-card field and means, "any sequence of one or
more characters here" .

The wild-card option is available on the following commands:
KILL
MOVE
DIR (wild-card field for entire file name only)

A new SVC has been added to allow Z-80 programs to use this wild-card capability.

To find a full description of wild-card use , use the Index .

Alternate Directory

For increased reliability of the diskette filing system, TRSDOS now sets up an
alternate directory. If the main directory should become unreadable, the alternate
directory will be used to allow continued access to the diskette. Details are given in
the descriptions of FORMAT and BACKUP.

ABSolute Option

Many of the TRSDOS commands and utilities ask the operator to confirm whether an
operation is to be completed. The ABS option has been added to eliminate these
questions and thus simplify the use of the command.

The ABS option is available on the following commands:

BACKUP
COPY
FORMAT
MOVE

MODEL II TRSDOS

Disk Swap Protection

The system now has the ability to detect when diskettes have been swapped
improperly , that is , while a file is open . TRSDOS will display an error message when
it detects this condition, and will cancel the read or write operation. See VERIFY.

New or Changed Supervisor Calls (SVCs)

These are described in the new pages for Section 4.

Name

VDCHAR

PRINIT

PRCHAR

LOOKUP

HLDKEY

OPEN

RENAME

WILD

RAMDIR

SORT

FILPTR

CLRXIT

VIDRAM

PRCTRL

A/BRCV

A/BTX

A/BCTRL

Function Code

Output a character to video 8

Initialize printer-driver parameters 1 7

Output a character to printer 1 8

(New) Lookup in a table 28

(New) Process the (HOLD) key 29

Open/Create a Program or Data File 40

(New) Rename a file 47

(New) Process a wild-card specification 5 1

(New) Read the directory into a RAM buffer 53

(New) Sort items in RAM list 56

(New) Get information about a currently 58
open file

(New) Execute CLEAR command and jump 57
to TRSDOS READY

(New) Transfer video to RAM or vice-versa 94

(New) Control printer operations 95

Receive character via Channel A/B 96/98

Transmit character via Channel A/B 97/99

(New) Control Channel A/B 1 00/ 1 1

VERSION 2.0 UPDATE

Changes to Basic

New Keywords

These are described fully in the new pages for Chapter 3 of the BASIC Reference
Manual.

Keyword Operation

ERRS$ Function Returns the last TRSDOS error number and message

NAME Statement Renames a diskette file.

Other Changes

PRINT Zones

The PRINT zone width is 16 columns (was 14). For example:

PRINT"*', ''B'V'C'V'D"
prints the letters in video columns 1 , 17, 33 and 49.

New Error Codes

TRSDOS error codes 47-48 now indicate FC errors in BASIC.

TRSDOS error code 49 now indicates an I/O error in BASIC, (Use ERRS$ to get the
TRSDOS error number and message . )

Line Printer

The maximum LPRINT or LUST line is 255 characters (was 1 32) ,

Passwords

You can assign a password to a program when you SAVE it. This password will be
required for loading or running the program.

Line Feeds

You can include line feeds in the program text, SAVE the program in ASCII format,
and LOAD the program later (used to cause a Direct Statement error). Each line feed
in the file requires two bytes of diskette storage.

Take care not to create a line that will require more than 255 bytes for storage. This
maximum includes the line number digits and the space following the line number.
If the line contains embedded line feeds, allow two bytes for each line feed.

MODEL II TRSDOS

OPEN Statement

To specify a record length of 256 , you can use either 256 or . For example ,
OPEN "D", 1 , "FILE", 256

and

OPEN"D",1,"FILE",0
are equivalent.

NEW

In addition to erasing the BASIC program in memory, this statement now clears the
screen.

re-

section 1

General Information

Model II TRSDOS

Introduction

Model II TRSDOS (' Triss-Doss' ') is a powerful and easy-to-use Disk
Operating System, providing a full set of library commands and utility
programs. In addition, many of the most useful System routines can be called
directly by user programs.

Library commands are typed in from the TRSDOS command level to
accomplish a variety of operations, including:

• Initialization -setting Printer parameters, date and time, etc.

• File-handling-copying, renaming, deleting, protecting, etc.

• File access- loading into memory, listing to Printer or Display, etc.

• Error identification

See the Commands section for details.

Utility programs provide essential services like:

• Formatting blank diskettes.

• Making backup copies of entire diskettes.
See the Utilities section for details.

System routines are executed via function codes instead of calls to absolute
memory addresses. Routines available fall into seven categories:

• System control

• Keyboard input

• Video Display input/output

• Line Printer output

• File access

• Computational functions

• Serial communications

See the Technical Information section for details.

General Information

Notation

For clarity and brevity, we use some special notation and type styles in this
book.

CAPITALS and punctuation

Indicate material which must be entered exactly as it appears. (The only
punctuation symbols not entered are ellipses, explained below.) For example,
in the line:

DIR SYS
every letter and character should be typed exactly as indicated.

lowercase italics

Represent words, letters, characters or values you supply from a set of

acceptable values for a particular command. For example, the line:

LIST filespec
indicates that you can supply any valid file specification (defined later) after
LIST.

. . . (ellipsis)

Indicates that preceding items can be repeated. For example:

ATTRIB filespec {option , . . . }
indicates that several options may be repeated inside the braces.

This special symbol is used occasionally to indicate a blank-space character
(ASCII code 32 decimal, 20 hexadecimal).
RENAME^ FILE/A jzfTO^FILE/B

x'nnnn'

Indicates that nnnn is a hexadecimal number. All other numbers in the text of

this book are in decimal form, unless otherwise noted. For example:

X7000'
indicates the hexadecimal value 7000 (decimal 28672).

Model II TRSDOS

Memory Requirements

TRSDOS occupies 6.1 tracks on the System diskette (39,040 bytes). However,
only a small portion is actually in memory at any one time. The Supervisor
Program, input/output drivers, and other essentials are always in memory.
Auxiliary code is loaded as needed into an "overlay area".

Memory addresses through 10239 (X'0'-X'27FF') are reserved for the Oper-
ating System. Certain commands, called "high overlays", also use memory
addresses up to X7FFF (details provided in the Commands section). User
programs must be located above X'27FF'; and you may want to locate them
above X'2FFF to allow use of the high overlays without loss of your program.

DECIMAL
ADDRESS

10240

12288

TOP*

32767 or
65535

SYSTEM AREA

USER AREA (SHARED WITH
TRSDOS "HIGH OVERLAY COMMANDS")

USER AREA UNTOUCHED*
BY TRSDOS

MAYBE

RESERVED BY TRSDOS FOR

SPECIAL PROGRAMMING

Last Memory Address

HEX
ADDRESS

X'0000'

X'2800'

X'3000'

TOP*

X'7FFF*or
X'FFFF'

MEMORY REQUIREMENTS OF TRSDOS

Note: The term "user program" applies to any program which is not a part of
TRSDOS. Therefore BASIC is a user program. For memory requirements of
BASIC, see the BASIC Reference Manual.

*TOP is a memory protect address set by TRSDOS. If TRSDOS is not protecting
high memory, then TOP is the same as "Last Memory Address".

** Single-drive COPY from one diskette to another, BACKUP and FORMAT use
all user memory.

General Information

Loading TRSDOS

See the Operation Manual for instructions on connection, power-up and
inserting the System diskette.

Note: A System diskette must be in Drive (the built-in unit) whenever the
Computer is in use. Whenever the Computer is turned on or reset, it will
automatically loadTRSDOS from Drive 0.

After the System starts up, it will prompt you to enter the date. Type in the
date in MM/DD/YYYY form and press ^^ .For example:

07/04/1979 02B3

for July 4, 1979.

Next the System will prompt you to enter the time. To skip this question, press
I3EBM • The time will start at 00:00:00.

/*~

To set the time, type in the time in
HH.MM.SS 24-hour form. Periods are
used instead of colons since they're
easier to type in. The seconds are op-
tional. For example:

14-30 11133

for 2:30 pm.

The System will record the time and
date internally and return with the
message:

TRSDOS READY

odel II TRSDOS

Using the Keyboard

TRSDOS distinguishes between upper and lower case letters.
Therefore

di r

is not the same as
DIR

Since TRSDOS commands are always capitalized, you'll probably find it
convenient to operate the Keyboard in the Caps mode (press ^S so the
red light comes on). That way, all the alphabet-keys are interpreted as capital
letters, regardless of whether the fflHI key is being pressed.

Certain control keys are useful in the Command Mode:

Interrupts line entry and starts with a new line.

Backspaces the cursor without erasing any characters. Use this to
position the cursor for correcting a portion of a line.

Forward-spaces the cursor without erasing any characters. Use
to position the cursor for correcting a portion of a line.

Backspaces the cursor, erasing the last character you typed. Use
this to correct entry errors.

Signifies end of line. When you press this key, TRSDOS will take
your command. Only those characters appearing to the left of
the cursor will be used.

General Information

SPACEBAR

Pauses execution of a command. Press once more to continue.
Not functional in all commands.

Advances the cursor to the next 8-column position. Tab
positions are at columns 0, 8, 16, 24, etc.

Enters a space (blank) character and moves the cursor one
character forward.

If you type any other control key (non-alphanumeric, non-punctuation), a
± symbol will be displayed for that key, but the control code will be sent to the
Computer. Such control keys will either be ignored or will cause a parameter
error to occur. See the Keyboard Code Map in the Appendix for control
codes.

Repeat key. For convenience whe n you want
to repeat a single key, hold down MW
while pressing the desired key. For example,
to backspace halfway back t o the beginning of
the line, hold down ^^B and

Model II TRSDOS

Entering a Command

Whenever the TRSDOS READY prompt is displayed, you can type in a
command, up to 80 characters. If the command line is less than 80 characters
(as is usually true), you must press [12010 to signify end-of-line. TRSDOS
will then "take" the command.

For example, type:

CL -S bjdid

and TRSDOS will clear the Display.

Whenever you type in a line, TRSDOS follows this procedure:

First it looks to see if what you Ve typed is the name of a TRSDOS command. If
it is, TRSDOS executes it immediately.

If what you typed is not aTRSDOS command, then TRSDOS will check to see if
it's the name of a program file on one of the drives.

When searching for a file, TRSDOS follows the sequence drive 0, drive 1, etc.
- unless you include an explicit drive specification with the file name
(described later on).

If TRSDOS finds a matching program file, it will load and execute the file.
Otherwise, you'll get an error message.

Keyaheads

TRSDOS also allows keyaheads of up to 80 characters. This means you can type in
the next command while previous ones are being executed.

Note: A keyahead will not be displayed until TRSDOS or the application program is
ready to interpret it.

Command Syntax

Command syntax is the general form of a command, like the grammar of an
English sentence. The syntax tells you how to put keywords (like DIR, LIST,
and CREATE) together with the necessary parameters for each keyword. In
this book, we present general syntax inside gray boxes, so they're easy to
recognize.

There are three general command formats:

1. No-file commands

2. One-file commands

3. Two-file commands

General Information

Syntax Forms

No-file commands

command { options } comment

options is a list of one or more parameters that may be needed by the
command. Some commands have no options. The braces { } around
options can usually be omitted when no comment is added at the end of
the command line.

comment is an optional field used to document the purpose of the command-
line. Comments are useful inside automatic command input files (see
BUILD and DO commands).

One-file commands

command filespec {options} comment

filespec is a standard trsdos file specification as described later in this

section.
options -See description above.
comment- See description above.

Two-file commands

command filespec-1 delimiter filespec-2 {options} comment

filespec- 1 and -2 are trsdos file specifications as described later in this

section.
delimiter is one of the following:

blank space or spaces (indicated as W)
a comma, surrounded by optional spaces
Ui(M surrounded by optional spaces.
options - See description above.
comment-See description above.

Model II TRSDOS

Examples of Syntax Forms

Empty option list
Command required because of comment

Comment

Command

Filespec

Option list

Comment

mlmzmzmm

Command

Filespec-1

Filespec-2

General Information

File Specification

The only way to store information on disk is to put it in a disk file. Afterwards,
that information can be referenced via the file name you gave to the file when
you created or renamed it.

A file specification has the general form

filmame consists of a letter followed by up to seven optional numbers or
- letters.
/mi is an optional name-extension ; ex? is a sequence of up to three numbers
orfetters,

.password is an optional password; password is a sequence of up to eight
rd is an opfionatdrive specif ication; d is one of the digits 0,1,2,3.
(diskette tm^e) is m dptioh&I field of up to 8 letters or numbers, ft this; ffeld is
ir^^y^; iim drive

Wd*#: jf here can be no blanks inside a file specification, trsdos terminates
the 1(0 ^ $p^ffteatton iatttie first blank space.

For example:

FileA/TXT. Manager :3( ACCOUNTS)

references the file named FileA/TXT(ACCOUNTS) with the password Manager,
on Drive 3, diskette name ACCOUNTS.

File Names

A file name consists of a name and an optional name-extension. For the
name, you can choose any letter, followed by up to seven additional numbers
or letters. To use a name extension, start with a diagonal slash / and add up to
three numbers or letters.

For example:

M0DEL2/TXT INVNTORY DATA! 1 /BAS
NAMES/ i 23 Au9 u s t / 1 5 WAREHOUS
TEST TEST! TEST/1

are all valid and distinct file names.

Model II TRSDOS

Although name-extensions are optional, they are useful for identifying what
type of data is in the file. For example, you might want to use the following set
or extensions:

/BAS BASIC program

/TXT ASCII text

/OBJ Object code

/ REL Relocatable machine-language program

/ D V R Input/output driver

/ S R C Source code

Wildcard

Certain library commands allow you to specify a collection of files by using a
"wild-card" field in place ofthe file name and/or extension. An asterisk "*" ina
file specification represents a wild-card field, and means, "any sequence of one or
more characters here" .

Unless restrictions are stated for a command, wild-card fields may take any of the
following forms:

Wild-Card Fields

* string
string*
*string*
string*string

Where string is a sequence of characters. The overall length ofthe wild-card field
depends on whether it appears in the file name or file extension.

For example:

MOVE */BAS:0 TO :1

copies all files with the extension ' 7BAS ' ' from drive to drive 1 .
DIR */COM:0

gives the drive zero directory, listing all user files with the extension ' 7COM" (DIR
allows a wild-card field only in place of the entire file name , and not in place of the
file extension.)

KILL *LST/*:0

kills all files with "LST" at the end ofthe file name, regardless ofthe other
characters in the name and extension. TRSDOS prompts you before deleting any file.

The wild-card option is available on the following commands:

KILL

MOVE

DIR (wild-card field for entire file name only)

General Information v M n

Drive Specification

If you giveTRSDOS a file command like:
KILL TEST/1

the System will search for the file test/i, starting at Drive and going to the
other drives in sequence 1,2,3 until it finds the file.

Anytime TRSDOS has to Open a file (e.g. , to List it for you) it will follow the drive
lookup sequence 0,1 ,2,3 . When TRSDOS has to create a new file, it will skip over
any write-protected or full diskettes.

It is possible to tell the System exactly which drive you want to use, by means
of the drive specification. A drive specification consists of a colon : followed
by one of the digits 0,1,2, or 3, corresponding to one of the four drives.

For example:

KILL TEST/ 1 S3
tells the System to look for the fileTEST/l on drive 3 only.

Passwords

You can protect a file from unauthorized access by assigning passwords to the
file. That way, a person cannot access a file simply by referring to the file
name; he must also use the appropriate password for that file.

TRSDOS allows you to assign two passwords to a file:

• An "Update word", which grants the user total access to the information
(execute, read, write, rename or delete).

• An "Access word", which grants the user limited access to the information
(seeATTRlB).

When you create a file, the Update and Access words are both set equal to the
password you specify. You can change them later with the PROT or ATTRIB
command.

A password consists of a period . followed by 1 to 8 letters or numbers. If you
do not assign a password to a file, the System uses a default password of 8
blanks. In this case the file is said to be unprotected; one can gain total access
simply by referring to the file name.

MODEL II TRSDOS

For example, suppose you have a file named secrets/bas. and the file has
MYNAME as an update and access word. Then this command:

KILL SECRETS/BAS
will not cause the file to be Killed. You must include the password myname
in the file specification.

Suppose a file is named domain/b as and has blank passwords. Then the
command:

KILL DOMAIN/BAS. GUESS
will not be obeyed, since GUESS is the wrong password.

Diskette Names

When you reference a file likeTESTER/BAS:3, TRSDOS will use whatever
diskette is in drive 3. However, if you add a diskette name to the file specifica-
tion, TRSDOS will first check to see that the correct diskette is in the drive.
(You assign diskette names during the Format or Backup process.)

Note: Only the COPY command looks at the diskette name and checks that the
correct diskette is inserted. The other commands ignore the diskette name.

A diskette name consists of from 1 to 8 letters and numbers inside parentheses
( ). When you include the diskette name in a file specification, you must
also include the drive number :d. Otherwise the diskette name will be ignored.

For example:
COPY REPORT/TXTS0 TO REPORT/TXT : 3( TXTFILES )

tells TRSDOS to copy the file REPORT/TXT on drive to another file named
REPORT/TXT on a diskette named txtfiles, using drive 3.

Section 2

Library Commands

Model II TRSDOS

Introduction

You can enter a library command whenever the TRSDOS ready prompt is
displayed. (Programs can also call library commands. See Technical
Information,)

The following commands use memory addresses from X'2800' to X'2FFF':

ANALYZE

CREATE

KILL

PURGE

APPEND

DUMP

LIST

RECEIVE

BUILD

ERROR

MOVE

SETCOM(alsoSVC55)

COPY

HELP

VERIFY

The following library commands use memory from X'2800' to TOP:

Single-Drive COPY

MOVE

RECEIVE (data goes into user area)

Other library commands use memory below X'2800' .

Exit Conditions of Library Commands

Any command executed from the TRSDOS READY level will return to TRSDOS .

Most library commands executed from another program can return to the program,
if the program uses this capability (see SVC 38, RETCMD) .

However, the following library commands will always exit to TRSDOS READY:

SPOOL ON

DEBUG ON

DO (exits to begin the first command in the DO-file)

HOST ON

MOVE

Single-Drive COPY

To continue program execution after any of these commands , you may use a DO-file
containing library commands and ending with a command to load and execute your
program.

Library Commands

r .

General rules for entering commands

Don't type any leading blanks in front of the command. For example:

TRSDOS READY
DIR

is an error. Omit the spaces before DIR.

There must be at least one space between the command and any option list or
comment. For example:

DIR{SYS}
is an error. Insert a space between R and { .

There can be any number of spaces between options.

DIR {SYS , prt}

has the same effect as:

DIR (SYS, PRT}

When no ambiguity would result, the braces around the option list can be
omitted.

CREATE FileA NRECS=100»LRL=64
is acceptable, but

CREATE FileA NRECS-100, LRL-64 Set up file area
is not, since the comment "Set up file area" will be taken as an invalid
parameter.

Details

When the syntax calls for a delimiter (tyTOty, comma or space), other non-
alphanumeric non-brace characters will also serve, unless the special
punctuation is part of an option keyword, e.g., the = sign in several
commands.

LIST TEXTFILE { PRT: SLOW}
is equivalent to:

LIST TEXTFILE {PRT» SLOW)

Model II TRSDOS

AGAIN

Repeat Last Command

AGAIN

This command tells TRSDOS to re-execute the most recently entered
command.

AGAIN cannot be used after certain library commands, utilities and user programs.

Example

TIME
AGAIN

TRSDOS will re-execute the TIME command.

Sample Use

AGAIN is useful after TRSDOS has returned an Input/Output error message
instead of obeying a command. For example, suppose you type:

KILL OLDFILErl
and the diskette in drive 1 is write protected. Then you'll get an ERROR 15
message. Put a write-enable tab on the diskette and type:

AGAIN
Now TRSDOS will re-execute the command.

Suppose you are making multiple backup copies of a file from drive to drive
1. Enter the COPY command once; for second and third copies, use AGAIN.
For example:

COPY DAYSWORKS0 TO DAYBW0RK:1

copies the file to a drive 1 diskette. Now put another diskette into drive 1 and
type:

AGAIN
to repeat the copy using the new diskette.

Library Commands w^i

ANALYZE

Analyze Diskette Allocation by Track

: ; : W :.,'■/■ \^::::^-y^ {pfovt = tracknumber}

fife isaTRS$c&f^ if form a of the command is

u&eW,th^^

^^^^
^^pfe^ T|ii$ option may Reused with either form of th^^

...;/>/■" : : x^^ ■ ■

j- #^ If this form of the command is used,

:^ tracknumb&r)w\\\ be

^ J ^ are currently using space on that track.

of the command.

This command allows you to determine how the diskette tracks are allocated to
system and user files. It may be useful before performing a BACKUP or XFERSYS
operation.

Example

ANALYZE DATAFILE

shows which tracks are used by the file named DATAFILE.
ANALYZE 1

shows which files are using each track on the drive 1 diskette.

Model II TRSDOS

APPEND
Append files

^-t and ffie-2 are file specifications. The files must have the

; ibQ^-^i-eliftsi^liefe 'itM:^r;C>: : in..fhe:OireGtory listing).
WtcM is a deHnu'ter, A comma or a space can also be used.

same type

APPEND copies the contents of file-1 onto the end of file-2. file-1 is unaffected,
while file-2 is extended to inciude file-1. The file types (V or F) and record
lengths (for fixed length record files) must match. See DIR for more
information on file types and record lengths.

Examples

APPEND Wordfile/2 TO Woi-df i le/i

A copy of Wordfile/2 is appended toWordfile/1.

APPEND REGION1 /DAT, TOTAL/DAT. guess

A copy of REGION1/DAT is appended to total/dat, which is protected with
the password guess.

Sample Uses

Suppose you have two data files, payroll/a and payroll/b.

PAYROLL/A PAYROLL/B

Atkins, W.R Lewis, G.E.

Baker, J.B Miller, L.O.

Chambers, C.P Peterson, B.

Dodson, M.W Rodriguez, F.

Kickamon, T.Y

You can combine the two files with the command:

APPEND PAYROLL/B TO PAYROLL/A

PAYROLL/A will now look like this:

Atkins, W.R

Baker, J.B

Chambers, C.P

Dodson, M.W

Kickamon, T.Y

Lewis, G.E

Miller, L.O

Peterson, B

Rodriguez, F

PAYROLL/B will be unaffected.

Library Commands

Model II TRSDOS

ATTRIB

Change a File's Passwords

ATTRIB file {ACC^pa$sword-lUPD^password-2, PROT^Ievel)
file is a file specification.
ACC=password-1 sets the access word equal to password- 1. If omitted,

access word is unchanged.
WD=pas8Word-2seis the update word equal to passwords If omitted,

update word is unchanged.
PROT-te protection level for access. If omitted, level is

- unchanged.

Level Degree of access granted by access word

NONE No access

EXEC 1*^ ■

READ Read and execute

WRITE Read, execute and write

RENAME Rename, read, execute and write

KILL Kill, rename, read, execute and write
(gives access word total access)

ATTRIB lets you change the passwords to an existing file. Passwords are
initially assigned when the file is created. At that time, the update and access
words are set to the same value (either the password you specified or a blank
password). See Chapter 1 for details on access and update passwords.

Examples

ATTR I B DATAF I LE ACC= JULY 1 4 , UPD-MOUSE ? PROT-READ
Sets the access password to JULY 14 and the update password to MOUSE. Use
of the access word will allow only reading and executing the file.

ATTRIB PAYROLL/BAS. SECRET ACOi
Sets the access word to blanks. The protection level assigned to the
word is left unchanged.

ATTR I B OLD/DAT . Apr 1 €• $ UPD= »
Sets the update word to blanks.

ATTRIB PAYROLL/BAS- PW PROT=EXEC
Leaves the access and update words unchanged, but changes the level of
access.

ATTRIB DATAFILE/i - PRN PROT=»
Sets the access level to Kill.

Library Commands 1

Sample Uses

Suppose you have a data file, PAYROLL, and you want an employee to use the
file in preparing paychecks. You want the employee to be able to read the file
but not to change it. Then use a command like:

ATTRIB PAYROLL ACOPAYDAY* UPD=Avocado» PROT=READ
Now tell the clerk to use the password payday (which allows read and execute
privileges only); while only you know the password, Avocado, which grants total
access to the file.

Suppose you want to temporarily stop access to the file. Then use the
command:

ATTRIB PAYROLL. Avocado PROT=NONE
Now the use of the password PAYDAY grants no access to the file. To restore
the previous degree of access, use the command:

ATTRIB PAYROLL- Avocado PROT=READ

Note: The EXEC protection level should be used to protect machine-language
programs ("P" attribute in the DIR listing) . Do not use this protection level for
BASIC program files, or the BASIC interpreter will not be able to load and run them.
BASIC programs must have a protection level of PEAD or higher.

Model II TRSDOS

AUTO

Automatic Command after System Start-Up

This command lets you provide a command to be executed whenever TRSDOS
is started (power-up or reset). You can use it to get a desired program running
without any operator action required, except typing in the date and time.

When you enter an auto command, TRSDOS writes command-line into the
start-up procedure for the diskette in Drive 0. TRSDOS does not check for valid
commands; if the command line contains an error, it will be detected the next time
the System is started up.

Examples

AUTO DIR {SYS}
Tells TRSDOS to write the command DIR SYS at the end of its start-up
procedure. Each time the System is reset or powered up, it will automatically
execute that command after you enter the date and time.

AUTO BASIC
Tells TRSDOS to load and execute BASIC each time the System is started up.

AUTO FORMS { W=80} For 8-1/2" wide paper-
Tells TRSDOS to reset the printer width parameter each time the system is
started up.

AUTO PAYROLL/CMD
Tells TRSDOS to load and execute PAYROLL/CMD (must be a machine-
language program) after each System start-up.

AUTO DO STARTER
Tells TRSDOS to take automatic key-ins from the file named STARTER after
each system start-up. See BUILD and DO.

Library Commands

To Override an AUTOmatic Command

Press (HOLD) any time during the DATE/TIME start-up initialization dialog (before the
second dNHH)).

To erase an automatic command

Type:

AUTO

This tells TRSDOS to delete any automatic key-ins and reset the start-up procedure to
go directly to the TRSDOS READY mode.

Important Note

Be sure a program is fully debugged before making it an automatic command.
Programs which are executed via the AUTO function shoul d norma lly provide a
means of exiting to the TRSDOS READY mode. (Unless the (BREAK) key is blocked by
the user program, pressing (BREAK) will get you back to TRSDOS . )

Sample Use

Suppose you want the TRSDOS to run a certain BASIC program, MENU, each
time it is started up. That way, an operator can turn on the Computer and get
going without having to enter any TRSDOS commands.

Then use the command:

AUTO BASIC MENU

to prepare the System to run the BASIC program each time it starts up. (See
BASIC Reference Manual for details on loading BASIC.)

Modelll TRSDOS

BUILD

Create an Automatic Command Input File

file is a file specification which cannot include an extension.

This command lets you create an automatic command input file which can be
executed via the DO command. The file must contain data that would
normally be typed in from the keyboard.

BUILD files are primarily intended for passing command lines to TRSDOS just
as if they'd been typed in at the TRSDOS READY level.

BUILDing New Files

When the file you specify does not exist, BUILD creates the file and
immediately prompts you to begin inserting lines. Each time you complete a
line, press [3311D . build will give you another chance to re-do the line or
keep it. Press B23 to erase and re-do the line; ^TOTl to store it and
start the next line.

While typing in a line, you can use Q and Q to position the cursor for
corrections. tlHS^^S also work s as usua l. Be sure the cursor is at the
end of the desired line before you press fam^l .

To end the BUILD file, simply press Bm?»l at the beginning of the line,
i.e. , when the message:

ENTER COMMAND LINE (1-80)

Is displayed.

Note: Pressing E5H33 will also end the file. Only those lines that have
been flagged like this:

*** LINE STORED IN FILE ***
will be saved.

Library Commands

Editing Existing BUILD-Files

When you specify an existing file in the BUILD command, TRSDOS assumes
you want to edit that file. Before starting the edit, it copies the file into a new
file with the same name but with the extension/OLD . That way, you will have a
backup copy of the file as it was before being edited.

Note: Editing an existing BUlLD-file requires that you have write-access to
the file. That is, if the access password has a protection level which does not
allow writing, then you must supply the update password.

Example

Suppose the file STARTER already exists, and you type the command:

BUILD STARTER

TRSDOS will first copy STARTER into a new file STARTER/OLD (if
STARTER/OLD already exists, previous contents are lost). Then it will let you
begin editing the file. As you edit the file, the updated lines will be written
into STARTER.

BUILD will display the existing contents of the file, one line at a time. Beneath
the line is an option list:

Ke e p ? De 1 e t e ? Re p lace? I n s e r t o r Q u i t ?

ENTER (K/D/R/I/Q) . . ?
Type the first letter of the desired option and press ^^^3 .

Keep Option: Copies the line as-is into the new file, and displays the next line
for editing.

Delete Option: Deletes the line by not copying it into the new file, and
displays the next line for editing.

Insert Option: Allows you to insert lines ahead of the line being displayed.
Using this option is like entering lines into a new file as described above.

After you press "P?nBs1 , TRSDOS will give you a chance to erase and re-
start the insert line, or to store the insert line. Press 0S3 to erase. ^ffl3
to store it. You can then insert another line.

To stop inserting, press HEH5E1 at the beginning of the line. TRSDOS will
then display the next line and the option list.

Replace Option: Deletes the displayed line and lets you insert replacement
lines. Entering replacement lines is like entering lines with the insert option.
Press Piffle at the beginning of a line to stop inserting. TRSDOS will
display the next line and the option list.

Model II TRSDOS

Quit Option: Ends the editing session. All remaining lines will be copied into
the new file as-is. Before closing the file, TRSDOS will ask you if you want to
add new lines to the end. (If you simply want to add to a file but make no other
changes, type Q at the beginning of the edit session.)

At end of file

Whenever TRSDOS reaches the end of the file, it will ask if you want to add

new lines at the end. Type Y BflMa to add, N HH-J to end the editing
session.

Adding lines at the end of a file is just like using the insert line option
described above. Type EMM at the beginning of a line to stop adding and
close the file.

To recover a BUILD file's previous contents

There are a couple of cases in which you may need to do this. Let's assume you
are editing a file named starter.

1. After ending the edit session, you realize that you have made an error,
and you want to recover the previous version of the file.

2. You accidentally press EHiEH and end the edit session; only those lines
that have been flagged like this:

*** LINE STORED IN FILE •***
will be saved in the new file named starter.

The previous file contents are now stored in starter/old. If you want to re-
edit this file, you must Copy it or Rename it to a file name without an
extension. For example, you might use this command:

COPY STARTER/OLD TO STARTER { ABS }

(See COPY for an explanation of the ABS parameter.) Now you can edit the
previous file's contents. Type:

BUILD STARTER
to start editing.

Library Commands

CLEAR

Clear User Memory

CLEAR

This command zeros user memory and returns to trsdos . It does not reinitialize the
I/O drivers , unprotect high memory , or perform any other functions .

Example

CLEAR

Model II TRSDOS

CLOCK

Turn on Clock-Display

This command controls the real-time clock display in the upper right corner of
the Video Display. When it is on, the 24-hour time will be displayed and
updated once each second, regardless of what program is executing.

TRSDOS starts up with the clock off.

Note: The real-time clock is always running, regardless of whether the clock-
display is on or off.

Examples

CLOCK
Turns on the clock-display.

CLOCK OFF
Turns off the clock-display.

Library Commands

CLS

Clear the Screen

This command clears the Display. Use it to erase information thai you don't
want others to see, for example, file specifications which include passwords.

Example

CLS

Sample Use

CREATE PERS0N1ML/BAS. secure NGRANS=300

Model II TRSDOS

COPY
Copy a File

COPY file-1 TQ file-2{mS}

file-1 and -2am file specifications,

te to bis a delimiter, Acornmaorspacecanalsobe used.

ABS is an optional p^ameter telliag f r^Idos to copy file- 1 even if
$£-2 already exists. The prevfeus contents of f/te*2will be lost If
ABS is omitted, copy will prompt you before it overwrites an
existing file,

COPY 'fifeTQ drive Jabs}

drivels the drive to which the file will be copied, using the same file
s|^cific^tionas/%

This command copies file- 1 into the new file defined by file-2. If a disk name is
included in either file specification, TRSDOS will ensure that the appropriate
diskette is inserted before making the copy. This allows you to copy a file from one
diskette to another, using a single drive if necessary . For single-drive copies,
specify the same drive number for each file.

When you do not add the ABS (' 'absolutely ") parameter, TRSDOS will not
overwrite an existing file that matches the specification///^ . Instead it will
prompt: "Existing file. Copy over it? (Y/N/Q)". Use the ABS option to overwrite
(destroy) an existing file without the prompt.

Normally, COPY uses memory below X'3000' '; however, when copying from
one diskette to another in a single drive, it will use memory up to the start of
unprotected memory (see Memory Requirements).

The diskette name, if used, must always be preceded by a drive specification;
otherwise it will be ignored.

Examples

COPY OLDFILE/BAS TO NEWFILE/BAS
Copies OLDFTLE/BAS into a new file named NEWFTLE/BAS. TRSDOS will search
through all drives for OLDFILE/BAS, and will copy it onto the first diskette
which is not write-protected.

COPY NAMEFILE/TXT:0(DEPTC) TO NAMEFILE/TXT : ( DEPTA )
This command specifies a one-drive copy from a diskette named DEPTC to
another diskette named DEPTA. trsdos will provide the necessary
prompting to accomplish the copy.

Library Commands

COPY FILE/A TO FILE/B: 1 (DOUBLE)
This command copies FILE/A to FILE/B. TRSDOS will search all drives for
FILE/ A, and will require you to have or insert a diskette named DOUBLE in
drive 1.

COPY NEWFILE TO OLDFILE { ABS }
Performs the copy even if OLDFILE already exists, in which case its previous
contents are lost.

COPY TESTPROG TO 3

Copies the specified file from the first drive that contains it onto drive 3 ,
using the file name TESTPROG.

Sample Use

Whenever a file is updated, use COPY to make a backup file on another
diskette. You can also use COPY to restructure a file for faster access. Be sure
the destination diskette is already less segmented than the source diskette;
otherwise the new file could be more segmented than the old one. (See free
for information on file segmentation.)

To rename a file on the same diskette, use rename, not copy.

Model II TRSDOS

CREATE

Create a Preallocated File

CREATE file {nGRANS-/?/, NRECS-n2, LRL-n3, TYPE-feffer}
file is afile specification.

NGRAN$==n.f indicates how many granules to allocate, if ngrans is
omitted, the number of granules allocated is determined by nrecs and

LRL

NRECS=n2 indicates how many records to allow for. If nrecs is omitted,

ngrans determines the size of the file. When nrecs is given, lrl must

also be given.
LRL=n3 indicates the record length (Fixed-length records only). n3 must be

in the range [1,256]. If lrl is omitted, lrl-256 is used. When lrl is

given, nrecs must also be given.
TYPE=letter specifies the record type: letter equals F (Fixed-length records)

or V (Variable-length records), If type is omitted, type=f is used.
NOTE: {ngrans} and {nrecs^lrl} are mutually exclusive.

This command lets you create a file and pre-allocate (set aside) space for its
future contents. This is different from the default (normal) TRSDOS
procedure, in which space is allocated to a file dynamically, i.e. , as necessary
when data is written into the file.

With preallocated files, unused space at the end of file is not deallocated
(recovered) when the file is Closed. With dynamically allocated files, on the
other hand, unused space at the end of the file IS recovered when the file is
Closed.

Note: With pre-allocated files, TRSDOS will allocate extra space when you
exceed the pre-allocated amount during a write operation.

You may want to use CREATE to prepare a file which will contain a known
amount of data. This will usually speed up file write operations, since TRSDOS
won't have to do periodic allocations during the write operations. File reading
will also be faster, since pre-allocated files are less dispersed on the diskette -
requiring less motion of the read/write mechanism to locate the records.

Examples

CREATE DATAFILE/BAS NRECS=300» LRL=256
Creates a file named DATAFILE/B AS, and allocates space for 300 256-byte
records.

CREATE TEXT/1 NGRANS=10B» TYPE=V
Creates a file named TEXT/ 1, and allocates 100 granules. The file will contain
variable-length records.

Library Commands

CREATE NAMES/TXT. IRIS NRECS=500, LRL=30

Creates a file named NAMES/TXT protected by the password IRIS. The file will
be large enough to contain 500 records, each 30 bytes long.

Determing the size of the file

You can allocate space according to number of granules or number of
records. (A granule contains 1280 bytes; a record contains from 1 to 256
bytes, depending on lrl.)

The granule is the unit of allocation in trsdos : if you ask for 30 granules,
that's exactly how much space the file will get (38,400 bytes).

If, on the other hand, you specify the number of records, trsdos will give
you the number of granules which are required to contain that many records.
For example, if you specify 100 records and a record length of 40 you're
asking for a total of 100* 40=4000 bytes. Since TRSDOS allocates spaces in
units of granules (1280 bytes), you'll actually get 4 granules -containing 5120
bytes.

Record Length (Fixed-Length Files Only)

A record is the quantity of data TRSDOS processes for you during disk
operations. The record length can be any value from 1 to 256.

File Type

TRSDOS. allows two types of files: Fixed-Length Record (FLR) files and
Variable-Length Record (VLR) files. With FLR files, the record length (from 1
to 256) is set when the file is created, and it cannot be changed. With VLR files,
the length of each record is independent of all other records in the file. For
example, record 1 might have a length of 70; record 2, 33; record 3, 225; etc.
Variable length records consist of a length byte followed by the data, and can
contain up to 256 bytes including the length byte.

For further explanation of file structure, allocation and types, see Technical
Information.

To Create a file to be used by BASIC

1. Decide how many records the file will contain. (This is just an estimate. If
the file exceeds this number, it will automatically be extended.)

2. If it is a Direct access file, determine the optimum record length (from 1 to
256). If it is a sequential access file, the record length must equal 1.

3. Use a CREATE command like this:

CREATE file { NRECS= number, LRL=length }

Model II TRSDOS

Sample Use

Suppose you are going to store personnel information no more than 250
employees, and each data record will look like this:

Name (Up to 25 letters)

Social Security Number (1 1 characters)

Job Description (Up to 92 characters)

Then your records will need to be 25+11+92= 128 bytes long.

You could create an appropriate file with the command:

CREATE PERSONNL/TXT NRECS=250, LRL-128

Once creaed, his preallocated file will allow faster writing than would a
dynamically allocated file, since TRSDOS won't have to stop writing
periodically to allocate more space (until you exceed the pre-allocated
amount).

Library Commands

DATE

Reset or Get Today's Date

DATE mm/dd/yyyy

mm is a two-digit month specification.
dd is a two-digit daysmen* specification.
yyyy i$wfww~n

If mm/dd/yyyy is given, trsdos resets the date. If mrn/dd/yyyy is omitted,
trsdos displays toe current date and time.

This command lets you reset the date or display the date and time.

The operator sets the date initially when TRSDOS is started up. After that,
TRSDOS updates the time and date automatically, using its built-in clock and
calendar. You can enter any four-digit year after 1599.

When you request the date, TRSDOS displays it in the format:

THU JUL 19 1979 200 -- 14-15.31
for Thursday, July 19, 1979, the 200th day of the year, 2:15:31pm.

Note: If the time passes 23.59.59, TRSDOS does not start over at 00.00.00.
Instead, it continues with 24.00.00. However, the next time you use the TIME
or DATE command, the time will be converted to its correct 24-hour value,
and the date will be updated. If you let the clock run past 59.59.59, it will
recycle to 00.00.00, and the date will not be updated to include the 60-hour
period.

Examples

DATE
Displays the current date and time.

DATE 07/18/1979
Resets the date to July 18, 1979, and displays the new information.

Model II TRSDOS

DEBUG
Start Debugger

DEBUG {switch}'

switch is one of the following parameters:

ON turns on the debugger.

OFF turns off the debugger.
If switch is omitted and debugger is off, trsdos tells you so.
If switch is omitted and debugger is on, trsdos enters the debug monitor.

This command sets up the debug monitor, which allows you to enter, test, and
debug machine-language programs. It also includes an Upload function to
allow transmission of data from another device to the Model II, via the built-
in serial interface (Channel B).

DEBUG loads into the high memory area sometimes reserved by TRSDOS for
special programming (see TRSDOS Memory Map). While DEBUG is on,
TRSDOS will automatically protect this area from being overlaid by BASIC or
other user programs. To use DEBUG from BASIC, you must turn DEBUG on
before you start BASIC.

While DEBUG is on, every time you attempt to load and execute a user
program, you will enter the debug monitor. In this mode, you can enter any of
a special set of single-key commands for studying how your program is
working.

DEBUG can only be used on programs in the user area X'2800' to TOP).

Examples

DEBUG
If DEBUG is off, this command tells you so. If it is on, this command enters the
debug monitor.

DEBUG OFF
Turns off DEBUG and un-protects high memory.

DEBUG ON
Turns on DEBUG: i.e., loads the debugger into high memory, protects high
memory, and sets up a "scroll window"- a block of lines that will be scrolled.
The scroll window will consist of the bottom 1 1 lines of the display. The top 13
lines will be used to contain the debug monitor display.

Library Commands

To enter the debug monitor

Type:

DEBUG ON
DEBUG

While DEBUG is on, you can also enter the debug monitor simply by typing the
file specification of a user program, trsdos will load the program and
transfer control to the debugger. The transfer address for the program will be
in the PC register display.

Start address of one

16-byte "row" of RAM.

RAM display-shows

hex contents of each
byte.

ASCII display-
period "." indicates
a non-displayable
character.

Z-80A register contents.

SZHPNC are the flag bits
in register F.

The ? is the command prompt, meaning that you can enter one of the single-
key commands. Press H (for "help") to display a "menu" or list of debugger
commands. To enter one of the commands, press the letter which is
capitalized in the command menu. For example, to enter the memory
command ("raM"), press H .

Model II TRSDOS

Most commands will prompt you to enter additional information or
subcommands. While entering commands and subcommands, the following
keys are useful:

B23 Returns to the ? prompt and cancels the command you're in.

EJa Backspaces the cursor and erases previous character.

Q Cursor back without erasing.

Q Cursor forward without erasing.

Q3 In certain subcommands, homes the cursor.

Ifil=l In certain subcommands, tabs the cursor.

Command Description
B (Breakpoint)

Press H to set a breakpoint in your program. When execution reaches a
breakpoint, control returns to the debug monitor, with the program counter
pointing to the breakpoint address. To continue from that point, press H .
The original instruction will be executed -but the breakpoint will not be
removed. It will still be there the next time that address is reached.

Note: Place breakpoints at the beginning byte of an opcode -never in the
middle of an instruction.

Press to enter the Breakpoint command. TRSDOS prompts you to enter
the breakpoint number. Up to eight breakpoints are allowed, so type in a
number from 1 to 8. Next TRSDOS prompts you to enter the new address for
that breakpoint. If the breakpoint has previously been set, TRSDOS displays
the old breakpoint address, and the original instruction that goes in that
address.

Note: While a breakpoint is in place, XT>7' is displayed in the memory display
for the breakpoint address.

For example:

? B #=i A-2800

Puts a breakpoint (#1) at address X'2800\ The memory display forX'2800' will
show aX'D7\

Library Commands

X'D7' indicates a breakpoint

has been set at this address.

To delete a single breakpoint without affecting any others, press
instead of providing a new address for the breakpoint. To delete all
breakpoints, press H for "Empty breakpoint table".

C (Continue)

Press H to enter this command. It resumes execution of your program at the
address pointed to by PC. Use it after the debugger has stopped at a
breakpoint. The original instruction at the breakpoint address will be
executed, but the breakpoint will remain in place.

D (Decimal Format)

Press El to enter this command. It displays all addresses in decimal form.
However, the contents of all registers and memory addresses are still
displayed in hexadecimal. In the decimal display format, you must enter all
addresses as five-digit decimal numbers.

E (Empty Breakpoint Table)

Press H to empty the breakpoint table. All breakpointed instructions will be
restored.

f Model II TRSDOS

F (Find Hex String)

Press S to start this command. It will search in memory for a string up to 20
bytes long. You must enter the search string in hexadecimal format. Press
B^^ when you have typed in the entire string. The debug monitor will
display the first occurrence of the string. If it is not in the search area, the
current memory display is unchanged.

For example:

F S=2800 E=4000 D=C30070
Searches memory from X'2800' through X'400(r for the three-byte hexadecimal
string X'C30070\ (' 'S -"is the prompt for start of search; "E = ", for end; "D = '\ for
data in hexadecimal form . )

X (Hex Format)

Press Q to restore the Display to hexadecimal format. In this mode, all
addresses must be entered as four-digit hexadecimal numbers.

J (Jump)

This is a two-step process:

1 . Type in the J-command and the jump address. This will load the address into the
PC register.

2 . Then use the C command to continue execution at that point .
For example:

?JA = 2800

Now press QD to start execution at X'2800\

L (Load or Copy memory to memory)

Type H to enter this command. It moves a block of memory. The debugger
will prompt you to type in the start (S=) and end (E=) addresses of the block
to be copied, and the destination address (T=) for the first byte moved.

The move is incremental: the first byte is moved to the first destination
address, then the second to the second destination address, etc.
Examples:

? L 5^2800 E-2BF0 T=3000
Copies addresses from X'2800' toX'28F0' into memory fromX'3000' toX'30F0\

Library Commands

You can use this command to fill memory with a specific value, by putting the
desired value in address nnnn, and using a command like this:

? L S=nnnn E=xxxx T—nnnn^ 1

This will copy the value in nnnn into every location from nnnn + 1 to xxxx + 1 .
For example, if X'2800' contains a X'20' , then the command:

? L 3=2800 E-3000 1=2801
fills memory from 2801 to 3000 withx'20\

O (Debug Off)

Type QD to exit the debug monitor and turn off DEBUG . All breakpoints set by the
B command will be removed from your program, and DEBUG will return to
TRSDOS . If you simply want to exit DEBUG, type: (T). DEBUG will remain "on' ' .

P (Print Display)

Type B to send a copy of the Display to the Printer. Printer must have been
initialized during TRSDOS startup or by the FORMS command.

M (Examine and Change Memory)

Type EI to enter this command. The debugger will prompt you to type in
the starting address of memory to be examined. As soon as you type in the
complete address, the memory display will show the 128-byte area starting

with that address. While the A= prompt is present, you can scroll

through memory 16 bytes at a time by pressing S^S *

To modify any memory in the display area, press HI while the

A= .... is displayed. The cursor will move up into the memory display area.

With the cursor in the memory display area, the cursor control keys are:

QBHH Cursor motion: back, forward, up, down

QB Homes Cursor

EZXO Tabs Cursor

^^^ Moves cursor to start of next row.

O Moves cursor in and out of ASCII area

When the cursor is in the hexadecimal area, enter hexadecimal values. The

debugger will update the memory display as you type in each nibble

(hexadecimal character, half a byte).

When the cursor is in the ASCII area, enter ASCII characters. Press
to return to hexadecimal entry.

To cancel all changes in memory, press H33 To effect all changes, press

m .

Model II TRSDOS

R (Modify Registers)

Press Q to enter this command. The R = > prompt appears. Type in a letter
indicating which register-pair you want to change:

A for AF B for BC D for DE H for HL

Xfor IX Yfor IY

F for AF' C for BC E for DE' L for HL'

The cursor will move over to the first byte of the register pair. While in the
register modify mode, use the cursor control keys,Qand{2to move over one
nibble at a time. Use MM to advance to the next register pair.

To cancel changes in register contents, press 1333 . To effect changes made,

press EH .

S (System)

Press H to return to the TRSDOS READY mode. The debugger is still on;
when you load and execute a program, you will enter the debugger again.

Model II TRSDOS

DIR

List the Diskette Directory

DIR :d {SYS t PRT}

:d is a drive specification. (The colon : before d is optional.) If :d is omitted,

drive is used.

SYS tells trsdos to list system and user files. If sys is omitted, only user

files are listed.
PRT tells trsdos to list the directory to the Printer. If prt is omitted, trsdos

lists the directory on the Console Display.

In addition to the above syntax, dir now allows the use of a special
wild-card file specification field in place of the drive specification in
which you specify an extension, but use a wild-card field in place of
the file name. In the dir command, the wild-card specification may
only be used in the following manner:

DIR7ex*:d

*lexi tells trsdos to list-all files with the extension ext

:d specifies which drive .is to be used. If omitted, drive zero will be
used.

The other dir parameters may also be used with this syntax.

If the sys option is used, only those system files with a matchi ng
extension will be included in the listing.

Examples

DIR
Displays the directory of user files in drive 0.

DIR 1 PRT
Lists to the Printer the directory of the user files in drive 1.

DIR { SYS* PRT}
Lists to the Printer the directory of System and user files.

The braces are required to prevent TRSDOS from taking sys as an invalid drive
specification.

DIR*/BAS:1
Lists all user files on drive one with the extension /BAS .

Library Commands

Sample Directory Listing

What the column headings mean

Disk Name — The name assigned to the diskette when it was formatted.

File Name — The name and extension assigned to a file when it was created.
The password (if any) is not shown .

Creation Date — When the file was created.

Update — When file was last modified.

Attributes — A four-character field.

The first character is either P for Program file or D for Data file.

The second character is either S for System file or * for User file.

The third character gives the password protection status.
X The file is unprotected (no passwords) .
A The file has an access word but no update word.
U The file has an update word but no access word .
B The file has both update and access words .

The fourth character specifies the level of access assigned to the access

word:

0, 1 Kill file and everything listed below.

2 Rename file and everything listed below .

3 Not used

4 Write and everything listed below .

5 Read and everything listed below .

6 Execute only.

7 None.

Model II TRSDOS

File Type — Indicates the record type for the file.
F Fixed-length records .
V Variable-length records .

Record Length — Assigned when the file was created (applies to
fixed-length record files only).

Number of Records — How many logical records have been written . Plus signs
(" + ") signify none have been written or file has variable length records and
number written cannot be calculated . If number exceeds 65535 , it starts over at zero .
That is, it is a modulo 65536 number. True number of records can be inferred from
Sectors Used column.

Number of Extents — How many segments (contiguous blocks of up to 32
granules) of disk space are allocated to the file.

$ Granules Allocated — How many granules are allocated to the file.

Sectors Allocated — How many sectors (256 byte blocks) have been allocated to
the file.

Sectors Used — Shows how many sectors have data written into them. Plus sign
(" + ") means no data in file.

@ A question-mark — means the file is open or was not properly closed .

Library Commands

Begin Auto Command Input from Disk File

DO///e

fife specifies a file ctBated with the buil^ command

This command reads and executes the lines stored in a special-format file
created with the BUILD command. The System executes the commands just
as if they had been typed in from the Keyboard, except that they are not
echoed to the Video Display (except for pause).

Command lines in a BUILD file may include library commands or file
specifications for user programs.

When DO reaches the end of the automatic command input file, it relinquishes
control to the last command it causes to be executed.

The DEBUG command cannot be included in an automatic command input
file.

Running User Programs from a DO-file

In addition to executing trsdos library commands, you can load and execute
user programs from a DO-file. You will probably want to make your program
name be the last line in the DO-file (see Note) . Before the DO-processor starts
the last line in the DO-file, it shuts off certain special functions so that your
program may execute normally (see Note below). For example, if you wanted
to perform some library commands and then run a basic program called
MENU, you would make this the last line in your program:

BASIC MENU

You can also "chain" do files, by putting another DO command at the end of a
DO-file. The DO command must be the last line in the DO-file.

Note: You can run user programs from the middle of a DO-file. The program
will run normally, with one important exception: pressing 133133 while
your program is executing will interrupt your program, terminate DO-file
processing, and return you to TRSDOS. Furthermore, your user program
cannot set up a II3I33 -processing program (see setbrk).

Model II TRSDOS

Examples

DO STARTER
TRSDOS will begin automatic command input from STARTER.

AUTO DO STARTER
Whenever you start TRSDOS, it will begin automatic command input from
STARTER.

Sample Use

Suppose you want to set up the following TRSDOS functions automatically on
start-up:

FORMS W=80
CLOCK ON
VERIFY OFF

Then use BUILD to create such a file. If you called it BEGIN, then use the
command:

AUTO DO BEGIN
to perform the commands each time TRSDOS starts up.

100

Library Commands

DUAL

Duplicate Output to Video and Printer

DUAL{SWttCh}

switch is one of the following:
on Turns on dual routing

off Turns off dual routing

This command causes all video output to be copied to the printer, and all printer
output to be copied to the display.

Notes:

1 . Printer and display output may be different, due to intrinsic differences in the
output devices and in the output software.

2 . Having dual routing on will slow down the video output process .

3 . If your printer is currently off-line or not powered-up the Video Display will
appear to be outputting about one character every three seconds (30 seconds if
you have run the LPII patch file) . You should turn off DUAL or ready your printer
to remedy this.

Sample Use

For a hard copy of all the system/operator dialog, turn on DUAL:
DUAL ON

101

Model II TRSDOS

DUMP

Store a Program Into a Disk File

DUMP file {START ^$ddress-1, END ^address-2, TRA^address-3

RELO ^address-4 t BORT= letter}

file is a file specification.

START ^address- 1 specifies the start address of the memory block.

END=addre$s-2 specifies the end address of the memory block.

TR A =addres$-3 specifies the transfer address, where execution starts
when the program is loaded. If omitted, address-4 is used.

REI^=adGfr^s-4^pecif ies the start address for loading the program back
into memory If omitted, acWre^s* 7 is used.

RORT=/effer specifies whether the program is directly executable from
trsdos. rort stands for "return or transfer". If rort-r, then trsdos
can load but not execute the file. If rort-t, then trsdos can load and
execute the file from the trsdos ready mode. If rort is omitted, rort-t
is used.

Note: Addresses must be hexadecimal form, withoutthe x 1 * notation.

This command copies a machine-language program from memory into a
program file. You can then load and execute the program at any time by
entering the file name in the trsdos ready mode.

You can enter machine language programs directly into memory, via the
DEBUG command.

Examples

DUMP LISTER/CMD START^7000* END=7100* TRA=7004
Creates a program file named LISTER/CMD containing the program in
memory locations X'7000' to X7100\ When loaded, lister/cmd will occupy

the same addresses. The program is executable for the TRSDOS READY level .

DUMP PR0G2/CMD START=6000i END=6F00, TRA=3010* RELO=3000
Creates a program file named PROG2/CMD containing the program in
addresses X'6000' to X'6F00' . When loaded, PROG2/CMD will reside from X'3000'
to X3F00'. Execution will start at X'3010\ The program is executable from
TRSDOS READY.

DUMP ROUTINE/1 START=6F00» END=6FFFi RORT-R
Creates a program file which cannot be executed from the trsdos ready
level. Typically, this would be a routine to be called by another program.

102

Library Commands

ECHO

Echo Keyboard Input to the Display

ECHO

This command allows you to type information on the Display without having
TRSDOS interpret it as a command. Press [BREAK] to stop ECHO and return to TRSDOS
READY.

Sample Use

You can key data directly to the printer by turning on dual routing and then starting
ECHO:

DUAL ON
ECHO

Now whatever you type will be output to the printer as well as to the display. (Most
printers will not print the line until a carriage return is received or the input buffer is
filled.)

103

f* Model II TRSDOS

ERROR

Display Error Message

ERROR number
number is a decimal number for a trsdos error code.

This command displays a descriptive error message. When TRSDOS gives you
a reverse (black-on-white) message like:

* * ERROR 47 * #
You type back

ERROR 47
to see the full error message.

Example

ERROR 3
Gives you the message

PARAMETER ERROR ON CALL

For a complete list of error codes, messages and explanations, seepages
4/1 1-4/ 12 of this manual.

104

Library Commands

FORMS

Set Printer Parameters

There are two syntaxes for this command:

A. FORMS {initialization-options}

B. FORMS {control-switch}

initialization-options may be any oombi nation of the following :
{} forms without any options sets all options to their default
values (listed below).

P = page length page length is a decimal number from o to 255
telling trsdos how many lines to a page. If omitted, 66 is used,

L = lines lines is a decimal number from to 255 telling trsdos
the maximum number of lines to print on a page before doing an
automatic top of form. If omitted, 60 is used. linesmusX always be
i ess than or equal to page length. If either equals 0, both must
equal 0. In this case, no automatic form feeds are done, and asgii
form feeds and vertical tabs are sent directly to the printer with
no translation.

W = width width is a decimal number from to ass telling trsdos
the maximum number of characters to print on a line before
doing an automatic carriage return. If omitted, 132 is used. If

sent directly to the printer with no translation.

C = control code control code is a one-byte hexadecimal code
which will be output to the printer upon completion of the forms
command.

control-switch may be any one of the following:

T tells trsdos to issue a form feed xoc character.

X tells trsdos to send all data directly to the printer without any
translation ("transparent" mode).

D tells trsdos to ignore all printer output, trsdos will not check
printer status ("dummy" mode).

fvl tells trsdos to return to "normal" (non-transparent,
non-dummy) mode.

A tells trsdos to output a line feed after each carriage return
("auto linefeed" mode) even if transparent mode is in effect,
tins coufttis updated by carriage returns but not by line feed
characters.

Q cancels auto line feed mode.

105

MODEL II TRSDOS

This command lets you set up the TRSDOS Printer software to suit the Printer you
have attached. If the default parameters p - 66, L = 60, W - 132, and C = are
appropriate, you do not need to use this command.

Summary of Special Option Combinations

Options Result

P > L * O Auto top of form; translate X'OC and X'OB' as carriage

return/line feed to advance paper to top of next page.

P = L =*= O No auto top of form, but translate X'OC and X'OB' as

carriage returns/line feeds to advance paper to top of
next page.

P = L = O

No auto top of form; send X'OC and X'OB' directly to
printer.

w * ° Automatic carriage return after W characters in a

single line; translate X'09' as 1-8 spaces to perform tab
function.

w = O No automatic carriage return; send XW directly to

printer without translation.

P = L = W = O Same as transparent mode except that line and width

counters are still updated.

For a complete discussion of TRSDOS printer software, see PRCHAR, PRINIT, and
PRCTRL in the Technical Information Section.

Examples

FORMS
Resets all parameters to their default values.

FORMS L=56
Resets the maximum number of printed lines per page to 56, leaving 10 lines
blank on each page.

106

LIBRARY COMMANDS

FORMSC-14

Sends the initialization code X' 14' to the Printer after resetting the default
parameters.

FORMS T

Advances Printer to top of form. Useful when you have done some printing and
want to start next printing at top of form.

FORMS S
Sets up the serial printer driver.

Setting the Parameters

Page Size. Multiply your form length in inches by the number of printed lines
per inch to get the appropriate value. Most Printers print 6 lines per inch.
Therefore standard 11-inch forms have a page size of 66 lines. That's why the
default is PAGE=66.

Lines per page. This number determines the number of blank lines at the
bottom of each page . If you set lines equal to page size , then TRSDOS will print
every line on the page. If you set lines equal to page size minus 6, then TRSDOS
will leave 6 blank lines on each page. Lines per page cannot exceed page size.

Width. This number sets the maximum number of characters per line. If a
print line exceeds this width, TRSDOS will automatically break the line at the
maximum length and continue it at the beginning of the next Print line.

Control Codes. Some Printers require an initialization code (for example, to
set up for double-size characters). The code you specify is sent to the Printer
during execution of the forms command.

107

Model II TRSDOS

Using a Serial Printer

The serial printer driver uses channel B on the back panel of the display console.
Connect your printer to this channel. Radio Shack's RS-232-2 Cable, Catalog
Number 26-4403, will work with many serial printers. If channel Aisnot
connected, place a serial terminator plug on that channel.

Before initializing the serial printer driver with FORMS, you must connect the
printer and execute the SETCOM command with parameters appropriate
for your printer. For example, if your printer uses 300 baud, 7-bit words,
no parity and 1 stop bit, you would use a command like this:

SETCOM B=(300,7, N, 1)

Then you would execute the forms command.

Technical Information

The serial printer driver uses the following pins of channel B (refer to the
Model II Operation Manual for a pin diagram):

Signal
Name

GROUND

DATA SET READY

CLEAR TO SEND

CARRIER DETECT

TRANSMIT DATA

REQUESTTOSEND

DATA TERMINAL READY

Pin#

7
6
5
8
/2
4
20

Note: If your serial printer does not support the clear to send signal,
connect pins 5 and 20 on channel B. If it does not support the DATA set
READY signal, connect pins 6 and 20 on channel B.

For a complete discussion of TRSDOS printer software, see PRCHAR, PRINIT, and
PRCTRL in the Technical Information Section.

During serial printer operation, TRSDOS will recognize two characters from the
printer:

ASCII Name

Hex Code

Function

DC3,"CTRL-S"

Pause printing

DC1,"CTRL-Q"

Resume printing

108

Library Commands

FREE

Display Disk Allocation Map

FREE :af PRT

:d is a drive specification. (The colon : before d is optional.) If :d is omitted,

drive is used.
PRT tells trsdos to send the map to the Printer. If prt is omitted trsdos
sends the map to the Console Display.

This command gives you a map of granule allocation on a diskette. (A
granule, 1280 bytes, is the unit of space allocation.) This information is useful
when you want to optimize file access time.

When a diskette has been used extensively (file updates, files killed,
extended, etc.), files often become segmented (dispersed or fragmented).
This slows the access time, since the disk read/write mechanism must move
back and forth across the diskette to read or write to a file.

FREE and ANALYZE help you determine just how segmented your disk files are . If
you decide that you'd like to re-organize a particular file to allow faster access, you
can then COPY it onto a relatively "clean" diskette.

Example

FREE
Displays a free space map of the diskette in drive 0.

FREE {PRT}
Lists the free space map for drive to the Printer. The braces are required in
this example, since no drive specification is included. Otherwise TRSDOS
would take PRT as an invalid drive specification.

FREE 2 PRT
Lists the Drive 2 map to the Printer.

109

Model II TRSDOS

A Typical FREE Display

Four special symbols are used in the FREE map:
Unused Granule
Directory Information
Allocated Granule

Granule Contains a Flawed Sector (Unusable)
Alternate directory.

D
X
F
A

Here's a typical display:

Disk name

X indicates an
allocated granule

D indicates

primary directory

A indicates
alternate directory

110

Library Commands 1

HELP

Help with TRSDOS Commands

specifies what trsdos command or general subject you '
Sample Use

HELP MOVE
gives the syntax for the MOVE command.

HELP SYNTAX
explains the format of the HELP messages.

111

Model II TRSDOS

HOST

Operate as a Host to a Remote Terminal

host {switch}

switch is one of the following:

ON Turns host function on.

off Turns host function off.

if switch is omitted, the on/off status is displayed.

This command allows the Model II to accept keyboard input from the RS-232-C
interface, and to transmit all display output to the same interface. Serial Channel A
is always used. While HOST is on, the Model II keyboard and the remote terminal
can both provide keyboard input; Model II output is duplicated to the Video Display
and to Channel A. Remote characters have a higher priority than local characters.

When you start HO ST, you have the option of enabling the remote (BREAK) key. If
you enable remote (BREAK) , the terminal will be able to interrupt operations just like
the console keyboard, by sending an ASCII x'03\ If you disable remote (BREM) . that
code will be ignored when it comes in via the serial interface. The HOST will process
a remote xw (null char) as if it were the local (HOLD) key.

Notes

1 . Before turning on the host function, initialize Channel A with the SETCOM
command.

2. At the remote computer, use the Model II TERMINAL program, or its equivalent.

3 . Channel A may not be turned off while HOST is active .

Sample Use

You have another computer connected to the Model II via a telephone modem. The
remote computer is running the Terminal program, and you want the Model II to
accept commands from the remote computer. Type in this command on the Model
II:

HOST ON

This tells the Model II to accept ' 'keyboard" input from the remote terminal , and to
echo all display output to the remote terminal .

To stop HOST operation, type:

HOST OFF

112

Library Commands

Swap Diskettes

You should execute this command immediately after swapping diskettes. It tells
TRSDOS to read the diskette id's on all drives in the system.

Note: Do not swap diskettes while a file is open.

See verify for related information.

Example

tells the System you have changed one of the diskettes.

113

Model II TRSDOS

KILL
Delete a File

KILLf/fe

file is a file specification.

Kill also allows for wild card fields In the file name and/or extension:
kill wildcard/wildcard

If no drive is specified, trsdos will search for all matching files on
drive only, if a drive is specified, trsdos will search only that
drive.

This command deletes a file from the directory and frees the space allocated
to that file. If no drive is specified, TRSDOS will search for the file, starting
with drive 0. Before deleting the file, trsdos will display the file name and
the drive that con tains the file. Type Y ^ S to Kill the file, N BHS to not
kill the file, or Q \*:u*:} to cancel the command.

Examples

KILL TESTPROG/BAS
Deletes the named file from the first drive that contains it.

KILL JOBFILE/IDY. foggy
Deletes the named file from the first drive that contains it. The file is
protected with the password foggy.

KILL FORM/ 123 S3
Deletes FORM/123 from drive 3.

KILLMY*:1

Tells TRSDOS to kill all drive 1 files which have a file name beginning with MY and
have no extension. TRSDOS will prompt you before killing each file.

KILLVBAS

Tells TRSDOS to kill all files on drive which have the extension /BAS.

114

Library Commands 1

Sample Uses

When updating a file, it is a good practice to input from the old file and output
updated information to a new file. That way, if the update is wrong, you still
have the old file as a backup. When you have verified that the update file is
correct, you can Kill the old file.

KILL is also useful in conjunction with pre-allocated files. Suppose you have
finished writing to a pre-allocated file, and one or more granules are unused
in the pre-allocated file. Then you can copy the pre-allocated file to a
dynamically allocated file, and afterwards Kill the pre-allocated file This is
the only way to reduce the size of a pre-allocated file.

115

MODEL II TRSDOS

LIB

Display Library Commands

LIB

This command lists to the Display all the Library Commands.

Example

LIB

116

Library Commands

LIST

List Contents of a File

LIST file { PRT, SLOW, R= record-number }
file is a file specificaton.

PRT tells trsdos to list to the Printer. If prt is omitted, the Console Display
is used.

SLOW tells trsdos to pause briefly after each record. If omitted, the listing

is continuous.
R^record number tells trsdos the starting record for the listing, record

number must be in the range [1 ,65535]. If omitted, record 1 is used.

This routine lists the contents of a file. The listing shows both the hexadecimal
contents and the ASCII characters corresponding to each value. For values
outside the range [X'20',X'7F'], a period is displayed.

To S^f Usting ' press ^ m ■ Press ^ m again to continue - Press raa

or IEmSI to terminate the listing.

Examples

LIST BATA/BAS
Lists the contents of data/bas.

LIST TEXTFILE/1 SLOW
Lists the contents of TEXTFILE/1, pausing after each record.

LIST TEXTFILE/1 R=100i A

The listing starts with the 100th record inTEXTFiLE/i. Only ASCII characters
are displayed.

LIST PROGRAM/ CMD PRT
Lists the file PROGRAM/CMD to the Printer.

117

Model II TRSDOS

Listing Format

LIST numbers each record as it is listed, and prints a heading showing the
relative position of each byte in the record. Here's a sample listing after the
command:

LIST ERRPRINT PRT

File
name i

R= 1
LftL= 256

Column
markers

Fixed or
variable
length records

Text on top row, hex on
next two rows. Period for
text indicates non-printable
data.

BYTE 1. . .5. . . 10. . . 15. .

. 35. . .40. . .45. ,

nw OCT 4 1979 277 - 12.26.31 PAGE 1

■50. - .""15. . .60. . .65. . . 70. . . 75. . .80. . .95, . . 90. . . 95 . . 100

1 - *ERRPR INT: IWEDOCT"?! 979276 0.22.4 1 10v ' 3-4 M o
^b™9^A^

-^-^"^^34031979., /600E^E4n^

™™™™™^^

0000000000B00000»00ia000»0000l3000000000000000000000000000

current record number and length

118

Library Commands

LOAD

Load a Program File

LOAD file

file is a file specification for a file created by the dump command.

This command loads into memory a machine-language program file. After
the file is loaded, TRSDOS returns to the trsdos ready mode.

You cannot use this command to load a BASIC program or any file created by
BASIC. See the BASIC Reference Manual for instructions on loading basic
programs.

Example

LOAD PAYROLL/pti

Note: You may not load a program file if it would overlay TRSDOS . The code must
be loaded above X'27FF' .

Sample Use

Often several program modules must be loaded into memory for use by a
master program. For example, suppose PA YROLL/pti and PAYROLL/pt2 are
modules, and MENU is the master program. Then you could use the
commands:

LOAD PAYROLL/Ftl
LOAD PAY ROLL / p 1 2

to get modules into memory, and then type:

MENU
to load and execute MENU.

If PAYROLL/ptl and PAYROLL/pt2 were Dumped with RORT-R, then you can
load by typing the file name without the LOAD command, i.e.,

PAYROLL/ Ft 1
PAYR0LL/Pt2

After each is loaded, TRSDOS ready returns.

119

Model II TRSDOS

MOVE

Copy Multiple User Files, Reorganize
a Diskette

This command takes two forms, A) and B) below.

A) move sourcefilB to drive {abs, prompt}

sourcefile is required. It is afile specification in which the name
and extension may be wild-cards. A password may not be used.
The wild-card fields allow you to specify a collection of files with
part of the fifename/pxtension in common.

drive is required, it is the destination of the copy operation, it can

specify any of drives o through 3 (single-drive moves are
allowed).

abs is optional. It tells trsdos to perform each copy operation even
if it will cause an existing file to be overwritten on the destination
drive. If abs is omitted, trsdos will prompt you before overwriting
afile.

prompt Isoptionai.IttellsTRSDOStodisplayeachfilebeforeitis
copied, and give you a set of options for that file. The options are
y/n/s/q (Yes— Copy; No— Don't Copy; Stop prompts and
proceed with all copies; Quit this command— no more copies.) If
prompt is omitted, trsdos will copy all files that match the
wild-card specification.

B) MOVEsource-drive to destin-drive {all, abs, prompt}

source-drive is required. It specifies which drive will contain the
files to be copied.

destin-drive is required, it specifies the destination of the copy
operation.

all tells trsdos to move all user files. This parameter is required
for form a of the move command.

abs and prompt are optional. They are explained above.

This command is similar to COPY, except that it allows you to copy a collection of
files with a single command line. Another difference is that the destination file is
always given the same name as the source file.

Note

Only user files without passwords may be moved .

120

Library Commands

Sample Use

Suppose you want to copy the following files from drive to another diskette on
drive 1 :

SORT/SRC
SORT/LST
SORT/REL
SORT/OBJ

Then use this command:

MOVE SORT/* TO 1ABS

TRSDOS will automatically copy all four files, and any others which match the
wild-card specification.

MOVE is also useful when you want to reduce the segmentation of files on a diskette.
The files will retain their relative positions in the directory listing, BACKUP cannot
serve this function, since it duplicates the file segmentation of the source diskette.

To perform such an operation from drive to 1 , put a formatted but empty diskette
in drive 1 , and use this command:

MOVE T0 1 ALL

You may perform this operation in a single-drive system, too. Specify drive as the
destination drive. There will be at least one swap per file to be moved, TRSDOS will
prompt you as required to swap source and destination diskettes.

121

Model II TRSDOS

PAUSE

Pause Execution for Operator Action

PAUSE prompting message
prompting message is an optional message to be displayed during the

P3US6,

This command is intended for use inside a DO file. It makes TRSDOS print a
message and then wait for the operator to press HSra-l .

Example

PAUSE

Insert Diskette #21

P i52£ AUSE folIowed b y the message and prompts the operator to press
EMia to continue.

PAUSE

Prints PAUSE and prompts the operator to press EE3 to continue See
BUILD and DO for sample uses.

122

Print a Text File

Library Commands

print iextfile {a,v}

tsxtfite speoifiesthe f ile to be printed. For normal use of the
mmmmdt the file should contain text characters only. It can
have fixed-length or variable-length records.

a tells trsdos to treat the first byte in each record as a forms
control character:

Contents

of First

Control

Byte

Function

"1"

Do a form feed before

printing (top of form)

"to" Carriage return before

printing (single-space)

"0" Two carriage returns before

printing (double-space)

" + " Carriage return without line-feed

advance. If your printer can do a
carriage return without a line-feed,
this control code will cause the
following characters to be overprinted
on the current line.

Only use this option when textfile contains these forms control
characters (e.g., rscobol list-files).

v tells trsdos to output to the video as well as to the printer. If vis
omitted, only the printer is used.

This command gives you printout of a text file . It does not show the record numbers
and hexadecimal codes (LIST does that) .

123

Model II TRSDOS

Notes:

1 . PRINT always tries to output to the printer. If you do not have a printer on-line,
this will normally give you an error. To avoid this, first execute the command:

FORMS D

which "dummies" all printer output. You can then PRINT to the video by using the
v option.

2. PRINT does a top of form before it starts printing.

3 . Unprintable characters (undefined control codes and codes
as periods.

Sample Use

> 127) are printed

Suppose you have a BASIC program named PROGRAM/TXT. It was saved in
ASCII-format. You can print it without starting BASIC. Type:

PRINT PROGRAM/TXTV

for video and printer output.

124

Library Commands

PROT

Use Diskette's Master Password

PROT :d {OLD = password, options}

:d is a drive specification. The colon is optional

OLD ^password specifies the diskette's current master password. (Your

TRSDOS diskette is supplied with the password password.)
options include any of the following :
NEW --password Gives TRSDOS the new master password (up to eight

alphanumeric characters) .
LOCK Tells TRSDOS to protect all user files with the latest master

password. Update and access words will both be set to this password.
UNLOCK Tells trsdos to remove passwords from all user files.

if lock and unlock are omitted, user file protection is left unchanged. If one is
used, the other must be omitted .

PROT changes file protection on a large scale. If you know the diskette's
master password, you can change it. You can also protect or un-protect all
user files.

A diskette's master password is initially assigned during the format or backup
process. The TRSDOS diskette is supplied with the master password
PASSWORD.

Example

PROT 1 OLD=-PASSWORD 9 NEW=H20

Tells TRSDOS to change the master password of the drive 1 diskette from
PASSWORD t0H20.

PROT 0LD-H20» UNLOCK
Tells TRSDOS to remove passwords from every user file on the drive diskette
(must have the password H20).

PROT 0LD=H20» NEW-ELEPHANT? LOCK

Tells TRSDOS to change the master password from H20 to ELEPHANT and
assign the new one to every user file.

125

Model II TRSDOS

PURGE
Delete Files

PURGE :d {file-class}

:d ii S s^T e Specification - The colon : is P tion a'- «* is omitted, drive is
fife-class is one or more of the following:
ddo System files (program and data)
PROG User machine-language program files
DATA User data files
ALL All files, user and system

If file-class is omitted.DATA is used.

This command allows quick deletion of files from a particular diskette. To use
PURGE, you must know the diskette's master password, (trsdos System
diskettes are supplied with the password password.)

Before eliminating any system files, read Disk File Requirements in Section 0.

When the command is entered, trsdos will ask for the diskette's password
Type in up to 8 characters, and press (ENTER) . The System will then display user
file names one at a time, prompting you to Kill or leave each file or Quit the
operation.

Example

PURGE 1

TRSDOS will let you purge data files from drive 1. This would include BASIC
programs.

PURGE
TRSDOS will let you purge data files from drive 0.

126

Library Commands

RECEIVE

Receive Object Code via RS-232-C

recei ve {OH - channel, offset}

channel is one of the serial channels, a or b.ch^ channel is
required.

offset isoptional. It tells trsdos to offset each load address
specified in the incoming data (see ''Required Data Format'',
below). It must use one of the following forms:

offset Result

ADD^hhhh The data load address is
incremented by the
hexadecimal value hhhh.

sm^hhhh The data load address is
decremented by the
hexadecimal value hhhh.
If offset is omitted, the data loads at the address specified in
the incoming data.

This command lets you receive object code into RAM from another device (a Model
I, II, or III, or other computer). The data must be sent in Intel Hex Format as
described later on.

Before using RECEIVE, you initialize one of the serial channels with SETCOM.
Select the appropriate parameters, depending on the requirements of the
transmitting device.

Notes

1 . The data will be loaded into memory according to the load information
contained within the data. It must load above X^FFF' and below the top of user
memory. (Execute the SETCOM command, then use the STATUS command to get
this last value.)

2. If the data load address is out of this range, you can use the offset option to bring
the load address into the desired range. Then, when the data is DUMPed into a
program file, use the RELO - hhhh option to specify the original load address.

127

Model II TRSDOS

Sample Uses

1 . You have initialized Channel A properly, and have established a connection
with the sending device. You know that the data load address is above X'2FFF
and below the end of user memory.

Now type:

RECEIVE CH- A

If the connection is good, Model II will display:

Ready to receive # =

The sending device can now begin the transmission . The number of the current
record will be displayed after # = . When the transmission is complete, Model
II will display:

START ADDRESS - aaaa LAST ADDRESS - bbbb TRA ADDRESS = cccc
TRSDOS READY

aaaa, bbbb, cccc are hexadecimal addresses.

The code will be in the memory area specified in the data itself. You can now
use the DUMP command to create a program file on diskette.

2. You have initialized channel B properly, and you have established a connection
with the sending device. But the load address is X'2800' . The end address is
X'37FF' . You need to add X'0800' to this address so that the receive program
won't be overlaid. Type:

RECEIVE CH - B ADD - 0800

This command causes the data to be loaded starting at X'2800' +
x'osocr^x'sooo'.

After receiving the data, you want to dump it into a program file called
PROGR AMI. Type:

DUMP PR0GRAM1 START - 3000 END - 3FFF RELO - 2800

Notice that the RELO - option resets the load address to its original value before
the data was transmitted.

128

Library Commands 1

Required Data Format

The transmitting program must send the data in "Intel® Hex Format' ' , described
below.

Each byte of data is sent as a pair of hexadecimal ASCII-coded characters:

1 ) high nibble (most significant four bits) , sent as first byte of pair.

2) low nibble (least significant four bits) , sent as second byte of pair.

For example, the value X'F7' is sent as two bytes, "F" (X'46') followed by "7"

(X'37').

Because only " : " and ASCII coded hexadecimal numbers are sent, data is always in
the range [X'30',X'3A'J or [x'4l',X'46']. Values outside this range will terminate
reception and produce an error message.

129

Model II TRSDOS

RECORD FORMAT

Records must be sent as follows:

CHARACTER
NUMBER

8 + (N*2)

9 + (N*2)

CONTENTS

High nibble of
record length (N)

Low nibble of
record length (N)

High nibble of msb
of load addr.

Low nibble of msb
of load addr.

High nibble of Isb
of load addr;

Low nibble of Isb
of load addr.

High nibble of Isb
of EOF (end of file)
code

Low nibble of eof
code

First byte of first
data pair

Second byte of first
data pair

First byte of last
data pair

Second byte of last
data pair

COMMENTS

Sync-character to indicate beginning of
record.

This 2-byte sequence gives the number of
byte pairs in this record. Zero means 256
byte pairs follow.

This 4-byte sequence gives address
where the data is to start loading. Address
specified must be in the user area [X'28oqv

TOP].

This byte-pair gives the eof code. Any
non-zero value means end of file (no more
records follow). A value of zero means
more records follow.

First byte is asch code for first hex digit;
second byte is ascii code for second hex
digit.

Last pair of data characters

130

Library Commands

CHARACTER

■ ~ . .

NUMBER

CONTENTS

COMMENTS

10+ (N*2)

First byte of data

checksum (high

This pair represents 2's complement of

nibble)

the data (all byte pairs after the ":" up to
but not including the checksum). Note that

11 + (N*2)

Second byte of

each byte pair is converted back to the

data checksum

Original byte of data before it is summed.

(low nibble)

.'■'■■■;

Sample record

CHARACTER

SAMPLE DATA

NUMBER

ASCII

HEX VALUE

'.' ■ ( *'-.'r ■

"0"

■■ : "■3" "■;--*

■■ ttQli ■■

A ; ;"'.''-'32'.'' : '

"2"

. • 5: ■■■:-■'.:

■ "^■r<"m- :■:.:■"

:"■■'.: 38 '!■■-'■

"0"

:ir - : - :,

:|"0"-

"0"

% -\ \

"0"

"3"

: ; :;: : ; :"T : y : : :

"7"

"0"

"A"

, ^

-■■ "3" -

— - — — _,

This record will contain 2 byte-pairs of data:

"3" "7" representing the value X'37'

" 7 " " " representing the value X ' 70'
and will start loading at X'2800' . The one-byte sum of the original bytes (represented
m pairs by characters 2 through 13) is X'5D\ The 2's complement of X'5D' is X'A3'
— which is represented in bytes 1 4 and 1 5 .

131

Model II TRSDOS

RENAME

Rename a File

REHAM£m-i TO ie-2
file- 1 and fffe-2 am file specifications. If file-2 includes a drive specification
^Password, it/Wff^^m^^Tte file will retain its former password, if

. any,.".' . ;■.;■;;.;■■

t/TCtf is a delimiter, A comma or sp&ce may also be used.

This command lets you rename a file. Only the name/extension is changed;
the data in the file and its physical location on the diskette are unaffected.

RENAME cannot be used to change a file's password. Use attrib to do that.

Examples

RENAME Miss/BAS TO Ms/BAS
TRSDOS will search for Miss/BAS starting with drive 0, and will rename it to
Ms/BAS.

RENAME REP0RT/AUGS3 TO REPORT/SEP
Renames REPORT/ AUG on drive 3 to report/sep.

RENAME MASTER. 12345678 TO MASTER/A
Searches for MASTER and renames it to MASTER/A. The password 12345678
must grant at least RENAME access (see Passwords in chapter 1). The renamed
file has the same password.

132

Library Commands

RESET
Reset/Restart TRSDOS

RESET

Executing the command is equivalent to pressing the RESET switch. The RESET
command closes all open files.

Sample Use

RESET

133

flVlodelllTRSDOS

SCREEN

Copy Screen to Printer

SCREEN

This command reads the contents of the display and outputs it to the printer.
Graphics characters will be represented as periods, and reverse alphanumeric
characters will be represented as normal characters.

Sample Use

You want to save a copy of a particular command line which is still on the screen
Type:

SCREEN

134

Library Commands

SETCOM

Set Up RS-232C Communications

SETCOM {A=$baudrate, word length, parity, stop bits),
B=(baud ram, word length, parity, stop bits)}

Toturnta

If A - (options) is omitted, status of channel A is unchanged.
B=(opf/oos) tells trsdos to initialize channel B.
To turn channel B off, use b=off.

If B = (options) isomitted, status of channel's isunchanged.
The options tell trsdos what RS-232C parameters to use, The following
parameters are available:
baudrate 110,150,300,600,1200,2400,4800,9600

If not specified, 300 is used.
word length 5,6,7,8

If not specified, 7 is used.
parity E for even, O for odd, N for none

If not specified, even Is used.
stop bits 1,2

If not specified, 1 is used.

Every option but the last must be followed by a comma. The options are
positional, e.g., the third item in an option list must always specify parity. To
use a default value, omit the option. If you want to list subsequent options,
you must include a comma for each default.

setcom without any options tells trsdos to display the status of
both serial channels.

This command initializes RS-232C communications via channels A and B on
the back panel. Before executing it, you should connect the communications
device (modem, etc.) to the Model II.

To change the settings on a currently active channel, you must first turn the
channel off. If the channel is already off when you try to turn it off, you'll get
an error message.

See the Model II Operation Manual for a description of RS-232C signals used in
channels A and B. For hard-wired connection from one Model II to another,
see the wiring diagram in Technical Information, RS232C supervisor call.

SETCOM uses the Special Programming Area above TOP (see Memory
Requirements). To use the serial I/O channels from basic you must execute
SETCOM before starting BASIC.

135

Model li TRSDOS

Once you initialize a channel , you can begin sending and receiving data, using six
system routines that are set up during initialization:

ARCV Channel A receive, function code 96

ATX Channel A transmit, function code 97

BRCV Channel B receive, function code 98

BTX Channel B transmit, function code 99

ACTRL Channel A control, function code 100

BCTRL Channel B control, function code 101

These system routines are only available when the respective channel has
been initialized, See Technical Information for details.

Examples

SETCOM A=< )
Sets up channel A for serial communications, using all the default parameters.
System function calls 96 and 97 are available for serial I/O. The status of
channel B is unchanged.

SETCOM B=(4800? 8» i
Sets up channel B:

baud rate 4800
word length 8 bits
parity Even (default)

stop bits 2

and turns off channel A.

2) » A-OFF

SETCOM A=*(24B05 8?
Sets up channels A and B:

Channel A
baud rate 2400

word length 8
parity Odd

stop bits 1 (default)

) » B= (

? *•:.

Channel B

300 (default)
7 (default)
Even (default)

SETCOM

displays the status of both channels.

SETCOM A = OFF, A = ()
resets channel A to default parameters.

136

Library Commands

SPOOL

Capture Printer Output or Print a Spool File

spool {switch}

switch controls the spool f unction Ji switch is omitted, the spool
status is displayed.

switch may be any one of the following :

on activates the spooler. This switch must be used before
any of the following switches can be used.

off turns off the spooler, and closes the capture- and
print-fifes.

N ( F=f//e closes the current capture-file and opens a new one
specified by file. If file is omitted, subsequent printer output
Will be dummied (ignored) until a capture file is named with n,
F=ffle.

p, F = file, k, c = copies, l - line begins spool-printing.

file is the file to be printed.

K Tells trsdos to keep the print-file after printing it. If k is
omitted, -the file will be deleted after it is printed, trsdos will
not delete a print-file if the file is closed by a spool s
command or if a disk error occurs in the print-file.

M^cagtim Specifies how many copies you want. If omitted,
one copy is made, c may be any number from 1 to 255.

L=//ne Specifies the line number where printing starts. A
line is defined sequence of characters terminated by a
carriage return. If omitted, printing starts at line one. l may
be any number from 1 to 65535.

h Halts spool-printing but saves the current position for later
resumption ("R" switch).

R,L=//ne Resumes spool-printing after a halt (h switch), or
displays the current line number if the spooler has not been
halted, ff L = tim is usedvprinting resumes at the specified line. If
L = line is omitted, printing resumes from where it was halted,

s- Stop printing. Closes but does not kill the print-file; leaves the
capture-file open.

137

Model II TRSDOS

CPU fd7dme) andT "^ ^ ^^ ° f the SyStem ^ e " redu <* the

CPU idle tune) , and to allow you to use the system while a print operation is in

progress. The TRSDOS spooler can perform two functions.

1 . It saves or "captures" the data that would normally go to the printer This
captured data may be thrown away, or it may be saved in a capture-file for later

2 . It prints data from a disk file while other operations are in progress . That is you
can be using the Model „ system _ ev(j ^ { for * O™

the file is being printed .

The two functions may be used one at a time or simultaneously. In the latter case
the spool-file 1S printed and real-time printer output is captured for later use. '

Sample Uses

1 . (Capture-File) You are going to run a program that outputs to the printer
Instead of waiting while the printing is done, you would like to capture it in a
disk file, and print it all out later. We'll call the capture-file SPOOLI . Type:

SPOOL ON

SPOOL N,F = SP00L1

Now all printer output will be saved in SPOOL 1 .
To stop capturing the printer output in SPOOL l , type :
SPOOL OFF

Now SPOOLI is a text file which may be LISTed or PRlNTed normally.

2 . (Print-file) You need to print a file created by the spooler, but you want to use the
system at the same time. Suppose the file is named SPOOL 1 , from the previous
example. The spooler is off. Type:

SPOOL ON

SPOOL P, F = SP00L1

TRSDOS will begin printing the file as a "background task" , meaning that
printing is performed only when the system is not busy with some
higher-priority operation like interpreting and executing your keyboard
commands. Since we did not include the K ore = copies option, TRSDOS will
delete SPOOLI after it is printed, and will print only one copy.

Spooler does not turn itself off after completing a print-file. To turn it off, type:
SPOOL OFF

3 (Simultaneous Capture-File and Print-File) You want to save real-time
printer output at the same time as the spooler is printing a file. In some
applications, this will be common.

For this purpose, you need one capture-file and one print-file. We'll use the
names SPOOLI andSPOOL2.

138

Library Commands

First turn the spooler on, and begin capturing printer output in SPOOL l :

SPOOL ON

SPOOL N,F-SP00L1

Now use the Computer normally, until you are ready to begin printing out
SPOOLl. When you are ready, type:

SPOOL N,F = SP00L2

This closes SPOOLl , and makes SPOOL2 the new capture-file. To begin printing
SPOOLl, type:

SPOOL P,F = SP00L1
Now SPOOLl will be printed, and any real-time printing will be saved in SPOOL2.
Suppose you want to halt the print-file operation. Then type:

SPOOL H

This does not affect the capture-file operation. To resume printing, type:
SPOOL R

Using the Spooler

1 . Spooler is invoked by the console command: SPOOL ON. This will cause a
high-memory module to be loaded and linked with the operating system.
Whenever spooler is active (resident in high-RAM) , the user must insure that this
high-RAM space is not overlayed with any programs or subroutines.

2. Before getting into the details of spooler, a brief explanation of how it works is
in order. Spooler itself can be thought of as a high level "supervisor' ' whose
role is to monitor the use of the ' 'physical" printer. As such, spooler can be said
to ' 'control" or "own" the printer. Spooler will accept your commands to print
out disk files of text to the real printer and will , upon your command, save all
data which was intended to be printed onto a disk file.

As long as spooler is active (or until you-issue the command line: SPOOL OFF) ,
all data that would normally go to the printer will be intercepted by spooler. This
is called the ' 'capture' ' function of the spooler. "Capturing" can be done to a
disk file of the name you specify in the command line:
SPOOL N F = filespec

' 'Capturing" can also be done such that all of the printed data bytes will get
"thrown" away — this is called capturing to a dummy file. In this case, no file
is opened and no data gets saved. There is a good use for this, as we will discuss
later. Because of this capturing function , your program is now said to be
outputting data to a " logical" printer, not the "physical ' ' printer.

139

Model II TRSDOS

While spooler is active, and while it is printing out a previously captured file, it
is using the extra processor cycles that would normally be wasted. Previously,
the computer would just wait for certain operations to complete; now, these
small time periods are used by the spooler to get the data from a disk file, then
output them to the real printer. Not only are wait times used, but, just to insure
that your printed report doesn't stop running altogether, some extra "time
slices" are given to the spool printer. The spooler, as you can now see, is a true
multi-tasked operation. The technique is more correctly known as
background/foreground processing, where the spool printer is a background
task, and your application program is a foreground task.

The capture function and the printing functions of spooler are separate . It should
be noted that the capture function is directly controlled by the application
program or utility that creates printed data. In BASIC, the "LPRINT" verb directs
data to the printer. Every time a byte is output to the printer, spooler, when
active, will intercept this byte and either output it to a disk file , as mentioned
above, or to throw it away. The time it takes to write the data out to a disk is
much faster than if it were going out to a real printer, due to the differences in
speed between a disk drive and even the fastest printers that you might use. This
feature alone can be used to speed up long jobs that prepare a printed report as an
output. The trade-off for the increased speed is, of course, disk space. Printed
reports usually take a lot of disk space to store. More on this later.

3 . Some of the features that spooler print has that should be helpful are listed
below:

A. The operator has control over the printing of the report from the disk file.
Such controls include pausing the report, stopping it altogether, resuming
the report, restarting the report on a certain line, and starting it up from a
certain line. The line positioning feature is especially useful when you only
need a certain part of a printed report, or if you ran out of paper, or the paper
jammed, while you were printing the report for the 1 st time.

B . Other operator controls include number of copies , and whether to keep or
delete the spool disk file after printing is complete.

C. Assuming none of the high-RAM where the spooler program resides has been
used for user subroutines , etc . , then the operator has the operational
flexibility to run spooler printing as desired. Again , spooler was designed to
be used without any application program modification to printer functions.

D. Special code has been installed that can sense printer faults in parallel
printers. This causes the printing function to just wait for the problem to get
corrected before the printing will resume. This should be especially helpful
when you have a paper jam or run out of paper. As soon as the printer goes
back on-line and is ready, spooler print will resume. Also, you may stop the
printer by taking it off-line (parallel printer only) so that you may look at the
printed material , and spooler will just "wait" for the printer to go back
on-line. If you have a serial printer that has the ability to send the DC3
character (X' 13') and the DC1 (X' 1 1 ') character, then you may use the DC3 to

140

Library Commands

pause the printer until the Model II receives the DCl (resume) character.
This is really a new feature in the printer software, not spooler, but applies
to spooler also.

4. While the spooler print function is running, programs may be run concurrently
with the printing. As a background task, spool printing will usually run as fast as
it can using the left-over computer cycles. There are, however, some programs
that cause there to be few extra computer cycles ; in this case , the printing
function will slow down. This is to be expected. Every effort has been made to
insure that the foreground task, your application program, will not be unduly
affected by the running of a spooler print file.

5. Other things which affect the speed of the spooler printing function are listed
below:

A. The number and frequency of disk input/output operations, i.e. , OPENS,

CLOSES , READS , and WRITES .

B . The printer you have, especially the size of its RAM buffer, and whether it is
a serial or parallel printer.

C . How often the processing program waits for keyboard input .

These all affect the spool print operation because, as a background task, the
spooler must wait for your processing program to finish some operations before
it can get control . Your program has a higher priority than the spooler and if
there is any competition for the same software in the operating system then the
spooler will take a ' 'back seat' ' to your program. An example would be: spooler
printer needs another disk record to continue its printing . Your program is
currently needing a disk record itself to continue processing . Spooler, in this
case, will wait for your disk operation to complete before it will request its next
disk record.

6. Spooler has, in its capture function, the ability to save or to throw away the
printed data. When it is first brought up, the capture function is set up to ' 'throw
away' ' the printed data until you specify (with the SPOOL N F = filespec
command) what the capture-file's file name will be. As soon as you do that, all
data bytes normally going to the printer will be captured into the data file you've
specified. The printed bytes will continue to be captured into this file until you
issue another SPOOL N F = command, which tells the capture function to close
out the first file, then open up another file to start capturing into. As soon as the
first file is closed, it may be printed. You may find it useful to delay printing of
this file until a later time. The only requirement is that the capture file must be
closed before it can be printed by the spooler print function.

When a capture file is open, you will notice that it appears in the directory with a
'?' after the file name. This is because the file is open and has not been closed.
Any other file which was opened and not closed will be marked in the same way
(see DIR command for details).

141

Model II TRSDOS

7. You may find it useful to setup the dummy capture mode, which is invoked by
the command SPOOL N F=<CR>. In this mode, all printed bytes will not get
saved on a disk file, but instead will be thrown away. The most common use for
this feature is when you have already run, and printed, the desired report but
you must rerun the program so that it can re-update or re-build the disk files that
it created. This will speed up the running of the program (in comparison to
having to print the report again) . Independent of this mode , you may still be
printing out another report, captured earlier, with the spooler print function.

8. It should be noted that, while spooler printer is running, the line count and
character counts that are kept by the operating system (see SVC PRCTRL) are
pertinent to the printing that is taking place by the spooler. This will usually
have no relationship to the data that your processing program might be
outputting to the capture file. Because of this, if your application program uses
this new printer control supervisor function, it will not give correct line counts
character counts, etc. to your program if spooler is running. This is because the
print software only keeps track of one set of line counts, character counts etc
and those values will be affected only by the spooler print function , not by the
data which is getting intercepted by the capture function. Consider this before
writing subroutines to use the new printer control supervisor function in your
applications. The use of these new functions will preclude the use of spooler
print while your program is running . Only when your program is outputting data
directly to the physical printer (which it is not the case if spooler is running) will
these line and character counts correctly reflect what the printer is doing at the
time.

Also, if your programs use the functions of setting line counts or character
counts , your programs should not be run when spooler is running . The results
will be unpredictable, and most assuredly, undesirable. The print control
functions relate to the physical printer, not to the ' ' logical ' ' printer that exists
when spooler is active . Your program , when spooler is active , outputs to the
"logical " printer which has no 1 ine counts , character counts , etc .

9. The amount of disk space that will be required to store a printed report that has
been captured is strictly a function of the size of the report itself— basically the
number of bytes of data. Certain techniques may be utilized to help speed up the
capture and to insure that you can get the most printed data in a file. These are
listed below:

A. It is recommended that you always use an empty diskette (a data diskette
with no other files on it is best) for the capture file, when you have a Disk
Expansion Unit and have an extra drive to dedicate to the capture file.

B. If your application or system doesn't allow the use of a separate, dedicated
drive for the capture file, then use a diskette with the most space available on
it that will be on-line when capturing is to take place .

C In either case above, using CREATE to set-aside the largest possible space for
the capture file will speed up the capturing itself— additional disk space
allocation will not be needed during the run.

142

Library Commands

D . Do not keep a capture file any longer than necessary so that the space on the
disk may be used for another capture file. The default, when printing out a
captured file, is for the captured file to be deleted upon completion of the
printing.

E. Try to avoid the outputting of large number of spaces in a printed report. If at
all possible, use the tab character (XW) instead of spaces, to ''position" to
the next printed column or field. The capture file will only have to store the
single tab character instead of the spaces. This will save on disk storage
space.

F. You might be able to move some of your data files from one disk to another
(in a multi-drive system) to free up the largest amount of disk space onto a
single disk for the capture file. This could slow down your other disk
accesses , depending on a lot of other factors , but this still might be faster just
because of using the capture function instead of a real , ' ' physical ' ' printer.

Some applications, because of the amount of free space on the disks, or
because of the size of the printed reports, will preclude the use of spooler.
Sample runs should show you what disk space requirements you might have
and what limitations of printed report size you might experience.

10. Spooler (either capture or printing) is compatible with:

A. Host

B . Serial Printer (SETCOM, FORMS S)

C. Do File Processing

D. Dual Routing

E. LIB commands PRT option (DIR, FREE, ANALYZE, LIST)

F. Communications (Some timing difficulties might be experienced at
higher baud rates)

G . Most utilities and LIB commands

1 1 . Spooler should never be run when formatter, or backup is running. In addition,
the disk that has the capture file on it should never be removed from the drive
until that capture file is closed and/or spooler is de-activated. Keep in mind that
when a printing function is currently in progress, the disk with the file being
printed must not be removed from the drive it is in, until the file is closed (and
deleted, if so desired). Depending on what else is going on, sometimes the
print file will remain open for several minutes after the printing has been
completed. Make sure by doing a directory , looking for the print file in the dir
before removing the diskette. The print file will not appear in the directory
with a. 4 ' ?" next to the name, because it was only opened for reading, not for
writing . Only files opened for writing will have this "?" appear in the DIR
listing.

143

Model II TRSDOS

Notes:

1. The SPOOL ON command cannot be called from BASIC or any user program
because it always jumps to TRSDOS ready upon completion. (Other spooler'
commands may be called from BASIC i.e. SPOOL N F = filespec etc )

2. When a capture file is first opened, the spooler writes a header record at the front
of the file. This consists of a "length" byte followed by the trsdos time-date
text. This information will not be printed by the SPOOL p command You can
create a spool print-file by following this format. If no header is to be used the
first byte of the file should be a binary zero. In this case, spool printing will
begin with the second byte. Spool files must have fixed-length, 2%-byte
records.

While the spooler is on and you have not named a capture file, all printer output
is ignored. To begin capturing the output, you must name a file (SPOOL N F =
file).

4 . While spool is ON and data is being captured and/or printed , the capture-file
and/or print-file are open . DO not remove the capture-file or print-file

DISKETTES UNTIL YOU H AVE TURNED THE SPOOLER OFF. Do not Backup or

Format to these disks, either.

5 . The capture-file traps all printer bytes — no translation is done . This is true
regardless of what print control options may have been selected (e.g. , auto
line-feeds). On the other hand, the print-file is output using the current selection
of print control options. For example, a X'OC will be captured literally; but a
X'OC in a print-file may be interpreted before it is printed, depending on the
currently selected print control options. See FORMS and SVC PRCTRL

6. When the spooler completes a print-file, it will not kill the print-file
immediately, but at the earliest opportunity. If you issue a DIR command
immediately after completion of a spool print operation, you may notice that the
file is still in the DlRectory. The file will be killed during execution of any user
program or any ' 'high-overlay" TRSDOS command such as LIST.

7. Once it has been closed, a spooler capture-file may be printed via the PRINT
command or by the spooler's print facility. However, the PRINT command will
not operate as a "background" operation allowing you to key in commands
during printing, and the time/date text will be printed at the beginning of the file.

144

Library Commands

STATUS

Display System Status Information

STATUS

This command tells you the first address of protected high-memory (non-user
memory), and list the on/off status of various TRSDOS functions are active.

Sample Use

You want to locate a Z-80 program at the top of memory . Use STATUS to find this
address:

STATUS

145

Model II TRSDOS

Advance Printer Paper to Top of Form

This command works like FORMS with the T option. Use it whenever you adjust the
printer paper position , or whenever you want to start a new page . If spooler i s
currently active and capturing, this will send Top-Of-Forms character X'OC to the
spooler capture file.

Sample Use

After PRlNTing a file, you want to start a new page:
T

146

Library Commands

TIME

Reset or Get the Time

TIME hh.mm.ss

hh is a two-digit hour specification.

mm is a two-digit minute specification.

ss is a two-digit second specification. If .ss is omitted, .00 is used.

If hh.mm:ssi& given, trsdos resets the time.

lihhmm.s$ is not given, trsdos displays the current time and date.

This command lets you reset the time or display the date and time.

The operator sets the time initially when TRSDOS is started up. After that,
TRSDOS updates the time and date automatically, using its built-in clock and
calendar.

When you request the time, TRSDOS displays it in this format:

THU JUL 19 1979 200 — 14-15.31
for Thursday, July 19, 1979, the 200th day of the year, 2:15:31 pm.

Note: If the time passes 23:59:59, TRSDOS does not start over at 00:00:00.
Instead, it continues with 24:00:00. However, the next time you use the TIME
or DATE command, the time will be converted to its correct 24-hour value,
and the date will be updated. If the clock is allowed to run past 59.59.59, it will
re-cycle to zero, and the date will not be updated to include the 60-hour
period.

Examples

TI HE
Displays the current date and time.

TIME 13.20.00
Resets the time to 1:20:00 pm.

TIME 18.24
Resets the time to 6:24:00

Note: Periods are used instead of the customary colons since periods are easier to
type in — you don't have to press (SHIFT) .

147

Model II TRSDOS

VERIFY

There are two syntaxes for this command ■

A. VERIFY {switch}

B. VERIFY {DETECT = switch]

switch is either on or off.

In syntax form A, sw/to/jtells trsdos whether to verify all diskette
writes (read after each write) . trsdos starts with this switch on If
omitted, the current status is given.

In syntax form B, switch controls the diskette id sensing feature. If
detect = on, then trsdos will automatically check the diskette id
before any diskette access, trsdos starts with the detect switch
on. If detect = off, then trsdos will not automatically check the
diskette id before each diskette read. In this case, you must use the
"I" command immediately after swapping diskettes.

This command controls the verify function. When it is on, TRSDOS will read
after each write operation, to verify that the data is readable. If the data is not
readable, after retries, TRSDOS will return an error message, so you'll know
mat the operation was not successful.

Note: TRSDOS always verifies directory writes. User writes (writing data into a
tile) are only verified when VERIFY is ON.

TRSDOS starts up with VERIFY ON. For most applications, you should leave it
ON.

While DETECT = ON: If the operator swaps diskettes while a file is open TRSDOS
will abort any attempted I/O to that file with error 7. When the correct diskette is
reinserted, TRSDOS will be able to perform the desired I/O operation.

When improper swapping is a possibility, programmers should write error-7
recovery procedures which prompt the operator to insert the correct diskette.

Examples

VERIFY ON
Turns on the verity function.

VERIFY OFF
Turns off the verify function.

VERIFY
Displays the status of the verify switch.

VERIFY DETECT = OFF
Turns off the diskette swap detection feature for reads only.

148

Section 3

Utility Programs

rModelllTRSDOS

Introduction to
Utility Programs

NAME

PURPOSE

BACKUP

Duplicate a Diskette

FORMAT

Organize a Diskette

MEMTEST

Ghecksout random access memory.

PATCH

Change contents of a disk file

TERMINAL

Communications program

XFERSYS

Transfer operating system

Several other "incidental" utilities are included: BASCOM, COMSUB and DOCOM
(all for serial communications); EXDATM and DATM (for date calculations); HERZ50
(for non-USA users); PRTBKSP; LPII.

The following utilities use memory from x'2800' to TOP, and exit to TRSDOS READY
upon completion:

BACKUP
FORMAT
MEMTEST
XFERSYS

To "chain" utilities and user programs, include them as commands in a DO-file.
The last command in the file may be one to load and execute your program.

150

UTILITY PROGRAMS

BACKUP
Duplicate a Diskette

BACKUP source TO destination {options}

source and destination are drive specifications. If omitted,
trsdos will prompt you to specify the source and destination
drives.

§ if no options are given, backup use defaults for ail the options.
The defaults are described below,

o0ons may be any combination of the following;

pw= source-password tells trsdos the master password of the
source diskette, trsdos will not duplicate a diskette unless you
give the correct password. If this option is omitted, trsdos wilt
assume the password is password.

new - dest-password tells trsdos the password to assign to the
destination diskette. The master password allows access to all
user files via the prot command, as well as full backup
privileges. If omitted, trsdos will use the password of the source
diskette.

id - diskette-name teils trsdos the diskette name to assign to the
destination diskette. If omitted, trsdos will use the diskette
name of the source diskette.

sy§^ tells trsdos to copy system files only. If omitted, all files will
**De copied (subject to prompt selections).

abs tells trsdos not to prompt the operator for diskette
information, but to use the information found on the source
diskette. If this option is used, trsdos will overwrite data on the
destination diskette without first warning the operator. If this
option is omitted, the operator may be prompted several times.

prompt tellsTRSDOS to promptthe user before each non-system
file is copied, allowing a selective backup. If prompt is omitted,
trsdos will copy all files without prompting.

noauto telisTRSDOsnottocopytheAUTOcommandinput(ifany).
If omitted, trsdos will copy any auto command input, (See-

AUTO.)

This utility allows you to duplicate some or all of the files on a system or data
diskette. The destination diskette must already be formatted.

Any two drives may be used for source and destination diskettes, or a single drive
may be used. In this latter case, TRSDOS will prompt you to swap source and
destination diskettes several times during the backup process.

151

ft MODEL II TRSDOS

Prompting Messages

Here are the prompting messages that may be displayed (depending on the options
given in the BACKUP command):

Source drive number? (0-3) ..

Type in the number of the drive that will contain the source diskette and press
CENTER) .

Destination drive number? (0-3) . .

Type in the number of the drive that will contain the destination diskette and press
CENTER) .

Source diskette ready? (Y/Q) . .

When the source diskette is in the proper drive , type Y CENTER) . To cancel the
backup operation, type Q (ENTER] .

DESTINATION Disk Ready? (Y/Q)..

When the destination diskette is in the proper drive , type Y CENTER) . To cancel the
backup operation, type Q (ENTER) .

Diskette contains DATA— use it? (Y/Q) . .

This warning will be given only if the ABS option is omitted and the destination
diskette contains file data. If you wish to overwrite existing information, type Y
(ENTER] , To cancel BACKUP, type Q CENTER] ,

Change Diskette Information?

This prompt will only be given if you do not use the ABS option. Type Y CENTER] if
yo u wish to change the password or diskette name on the destination diskette . Type
N (ENTER) if you wish to copy this information from the source diskette.

If you selected the Change option, TRSDOS will prompt you as follows:

Enter New Password

Type in the password to be assigned to the destination diskette and press (ENTER] .

Enter New Disk Name

Type in the diskette name to be assigned to the destination diskette and press
CENTER) .

If you selected the PROMPT option, the following prompt will be displayed before
each user file is copied:

f/te?(Y/N/S)..

file indicates the current file. To copy it, type Y CENTER) . To skip it, type N CENTER!
To copy it and stop the prompts , type S (ENTER] .

152

Utility Programs ^§|i

Primary and Alternate Directories

The primary directories of the source and destination diskettes must be on the same
track.

The alternate directories may be on different tracks; in fact, the alternate directory
need not be present on either diskette. If the destination diskette does have an
alternate directory, it will be used as such, even if the source diskette has no
alternate directory. If the destination has no alternate directory, none will be
created, even if the source diskette has an alternate directory.

During the BACKUP process, the source diskette's primary directory will be used
unless it is found to be flawed. In this case, the alternate, if available, will be used.

If the destination diskette contains an alternate directory on a track which is used for
data on the source diskette, the backup will be cancelled.

Other Messages and Error Conditions

This is not a comprehensive listing; self-explanatory messages are not included.

Source diskette ERROR
Only GOOD files can be copied
Continue anyway? (Y/Q)

TRSDOS cannot copy the current file, due to a flaw in the diskette or some other
error. Type Y (ENTER) to continue with the next file; Q (ENTER) to cancel the backup.

If any of the following errors occurs, you should:

1 . Recreate the steps which caused the problem and duplicate the error.

2 . Call Radio Shack Customer Service for a system error report.

DUALALLOCATION
Two files contain overlapping space allocations,

ALLOCATED ON FLAWED TRACK
A file has space allocated on a flawed track.

ALLOCATION ERROR
There is a conflict between space allocations and the free space map.

153

MODEL II TRSDOS

Using BACKUP To Recover Data (Alternate Directory
Required).

Of all tracks on a diskette, the directory is used the most, therefore it tends to wear
out first. When a primary becomes unreadable, TRSDOS cannot perform normal
disk I/O using that diskette. If an alternate directory is available, TRSDOS will use it
automatically. This will slow down disk I/O.

If you begin having diskette errors with a particular diskette, use BACKUP with a
destination diskette which is known to be good (no flaws). During the backup
process, TRSDOS will use the alternate directory, if one is available and is needed, to
recreate a good directory on the destination diskette. (If the destination has both
primary and alternate directories, both will be contain the same good information.)

154

Utility Programs

FORMAT

Erase and Initialize a Diskette

FORMAT drive {options}

drive Specifies which drive is to be used for the format operation.
drive is the drive number. 0, 1 , 2, or 3. If omitted, trsdos will
prompt you for the drive number.

{} If no options are given, trsdos will use defaults, as given
below.

abs Tells trsdos notto warn the operator if the destination
diskette contains data. If abs is omitted, trsdos will always warn
the operator before overwriting a version 2.0 diskette which
contains file data.

id = diskette-name Tells trsdos the name to assign to the
diskette. lfomitted,TRSDOSwillbeused.

pw= password Tells trsdos the master password to assign to
the diskette, if omitted, password will be used. The master
password allows access to all user files (via the prot
command), and also allows full backup privileges.

dir = tracknumber Tells trsdos where to place the primary
directory. If this option is omitted, track 44 will be used. The
primary directory may be placed on any track from 1 -76.

Warning: system/sys requires 7 tracks following directory if
diskette is not a data diskette.

alt- tracknumber Tells trsdos where to place the alternate
directory. If tracknumber^ 00, no alternate directory will be
created. Ifthe alt option is omitted, the primary directory track
number plus 8 will be used. If the specified or computed
tracknumber> 76, track 1 will be used.

verification levei is one of the following:

FULL Reads each sector and compares the

value against what was written during
initialization.

NONE No verification is done.

If no verification level is specified, full is used.

This program initializes a diskette by defining the tracks and sectors , and writing
system information onto the diskette. (For more information on the TRSDOS
diskette format, see Technical Information.)

The diskette may be blank (new or bulk-erased) or it may already be formatted.
When you re-format a diskette, all previous information is lost.

155

Model II TRSDOS

Verification

FORMAT also does a specified amount of verification, or checking for areas on the
diskette which cannot store data due to flaws in the recording surface. If it finds a
flawed area, TRSDOS "locks out" the affected track and will never try to use that
track.

Whenever you format a new diskette, use the FULL verify option. This takes longer,
but gives greater protection against lost data due to a flawed track .

When you are re-formatting a diskette which has been functioning without diskette
errors, the NONE option may be sufficient. NONE is faster than FULL, since no
verification is done. But remember, for greater reliability, FULL verification is
recommended.

Main and Alternate Directories

TRSDOS maintains a primary directory on each diskette . Unless you use the ALT - 00
option, TRSDOS will also maintain an alternate directory.

For general applications , you should always have an alternate directory . If a
diskette's primary directory should become unreadable, the alternate directory will
automatically be used instead — so that you don't lose access to the data on that
diskette. See BACKUP, Using BACKUP to Recover Lost Data.

Selecting the Directory Tracks

TRSDOS allows you to specify where the directories will be placed. The default
locations are:

Primary = 44 Alternate = 52

For general purposes, this will be the most efficient arrangement.

Notes on Directory Location

1 . If you are going to put TRSDOS on the diskette , be sure there are seven
contiguous good tracks immediately after the primary directory.

2. The greater the spread between the primary and alternate directories, the longer
it will take TRSDOS to update them. A spread of 8 tracks is recommended . This
isolates the directories without separating them unduly.

3 . If the diskette is to contain the TRSDOS system (full or minimum), there must be
seven good contiguous tracks following the primary directory. For this reason,
the primary directory track number must be less than or equal to 69 .

4. FORMAT will not place a directory (primary or alternate) on a flawed track. If
you specify a track (DIR = or ALT = ) which is flawed , TRSDOS will use the
default track (DIR - 44, ALT = 52). If the default track is bad , TRSDOS will place
the directory on the first good track after this one. TRSDOS will abort the
operation if it doesn't encounter a good track within five tracks of the default
track.

156

Utility Programs ||f||

5 . In some applications you may want to use different directory positions . For
example, if a data (non-system) diskette is to contain only one user file, it may
be efficient to place the directory on track 1 so that tracks 2-76 are available for
the file.

For another example, suppose tracks 44-49 are flawed , preventing TRSDOS from
placing the directory there. In this case, you may locate the primary directory on a
good track, so the diskette will still be usable.

Examples

FORMAT

TRSDOS will prompt you for the drive to be used, but will use defaults for all the
options.

FORMAT 1 {ID = ACCOUNTS, PW - MOUSE}

TRSDOS will use drive 1 ; the diskette will be named ACCOUNTS with the password
MOUSE.

FORMAT {ABS,N0NE}

TRSDOS will prompt you for the drive to be used, will use no verification, and all
other options will be defaulted.

FORMAT 1 {DIR = 01 , ALT = 02}

Drive 1 , primary directory on track 1 , alternate on track 2. This leaves all unused
space in one extent . The resultant diskette can not be used to contain TRSDOS , since
there are not seven free tracks immediately following the primary directory.

FORMAT 2 {DIR = 40}

Drive 2, primary directory on track 40, alternate on track 40 + 8 = 48.

When to Format

To prepare a new diskette.

Before you can use a new diskette, you must format it. After formatting,
record the disk name, date of creation and password in a safe place. This will
help you estimate how long a diskette has been in use, and prevent your
forgetting the master password. (For this application, always use the FULL
verify option.

To erase all data from a diskette.

To "start over" with a diskette, you can format it.

To lock out flawed areas.

After long use, flaws may develop on a diskette. Reformat the diskette to lock
out these tracks while leaving the good tracks available for data storage. Use
the FULL verify option for this application.

157

ModelHTRSDOS

MEMTEST

This utility tests the random access memory in the Model II . You may select either a
full memory test (X'0000' to end) or a user memory test (X'300(r to top of user
memory).

To execute the test, type under TRSDOS ready:

MEMTEST (ENTER]

Note: After running the full memory test, you must reset the system. After running
the user memory test, control returns to TRSDOS READY . All user memory is
cleared. None of the high-memory routines may be active while MEMTEST is
running. (The STATUS command will tell you if any are active.)

158

Utility Programs

PATCH

Change the contents of a disk file

patch programfile A-address, F^findstring, C=changestring

This is the form to use when you are patching a program stored with the "P"
(program) attribute (see dir). Files created with dump will fall into this cate-
gory.

programfile specifies the file you want to. change. If it is a system file, no
password is necessary. If it is a protected user file, the password must be
included.
A-=aaaa

aaaa is the starting address of the data to be changed. This is where the

data resides in memory when the program is loaded, aaaa is a four-digit

hexadecimal value without the X' ' notation.
F= findstring specifies the string that is currently in the patch area.
C=Ghangestrmg specifies what data is to replace findstring. changestring

must contain the same number of bytes as does findstring.

Both findstring and changstring can be in hexadecimal or ascii form. In
hexadecimal form, each byte to be changed is represented as a two-digit
hexadecimal value. In ascii form, each byte to be changed is represented
by the ascii character corresponding to that byte value, ascii strings must be
enclosed by single or double quotes.

patch datafile R^record, B^startingbyte, F ^findstring, C^changestring
This is the form to use when you are patching a data fNe, i.e., a file stored with
the "D" attribute (see dir);SASJC programs and data filesfallintothis category.

datafile specifies the file you want to change. If it is a system file, no password

is necessary. If it is a protected user file, the password must be included.
FNrecord

record tells which record contains the data to be changed, and is a decimal

number from 1 to 65536.
B-startingbyte

starttnghyte specifies the position of the first byte to be changed. If is a

decimal number from 1 to 256.
F^findstring and C= changestring are described above

159

MODEL II TRSDOS

This utility lets you make minor corrections in any disk file, provided that:

1. You know the existing contents and location of the data you want to
change.

2. You want to replace one string of code or data with another string of the
same length.

You can use PATCH to make minor changes to your own machine-language
programs; you won't have to change the source code, re-assemble it, and
re-create the file. You can also use it to make minor replacement changes in
data files.

Another application for PATCH is to allow you to implement any
modifications to TRSDOS that may be supplied by Radio Shack. That way,
you do not have to wait for a later release of the operating system.

Note: If you press 0H333 during a patch operation, before any changes
have been made in the file, PATCH will close the file and return you to
TRSDOS. The file will be unchanged. Once patch has begun changing the
file, pressing 11 51133 will have no effect.

Using PATCH on a TRSDOS System File

When Radio Shack releases a modification to trsdos, you will receive a
printout of the exact PATCH commands that are required to perform the
change.

To implement such a change, you would follow these steps:

1 . Make a backup copy of the diskette to be patched .

2. Insert the TRSDOS disk to be changed into one of the drives. The diskette must be
write-enabled.

3. In the TRSDOS READY mode, type in the specified PATCH command.

4. After completion of the patch, test the diskette in drive zero to see that it is
operational as a TRSDOS system diskette. You will have to reset the Computer.

160

UTILITY PROGRAMS

Using PATCH on a Program File

Remember that in this context, "program files" refers strictly to those files
stored with the "P" attribute. Use the DIR command to find out the attributes
of a file. BASIC programs have the "D", not the "P", attribute. (See
instructions for changing data files.) Program files are created with dump.

Suppose you want to change seven bytes in a machine-language program file.

First determine where the seven-byte sequence resides in ram when the

program is loaded. Then make sure that your replacement string is the same

length as that of the original string. For example, you might write down the

information as follows:

File to be changed: vdread

Start address: X'5280'

Sequence of code to be changed: X'CD2C25E5'

Replacement code: X000000C9

Then you could use the following command:

PATCH VDREAD A - 5280, F = CD2C25E5, C - 000000C9

Using PATCH on a data file (including BASIC programs)

If the file is stored with the "D" attribute, you specify the patch area in terms
of the logical record which contains the data, and the starting byte of the data
in that record. (The TRSDOS list command gives this information.)

For example, suppose in a file called namefile you need to change a 12-byte

sequence. When you LIST the file, you find that the sequence is located in

record 128, and that the sequence starts at byte 14. Write down the

information like this:

File to be changed: namefile

Record number: 128

Starting byte: 14

Sequence of text to be changed: "JOHN'S DINER''

Replacement text: "JACKS PLACE''

Then use the following command:

PATCH NAMEFILE R = 128, B = 14, F = "JOHN'S DINER", C = "JACK'S PLACE"

Notice that either string can include a single-quote, as long as the string is
surrounded by double-quotes. If you wanted to include a double-quote inside
either string, you would have to enclose that string in single-quotes.

Note: The string you are changing must be wholly contained inside the
specified record. If it spans two records, you will have to perform the patch
operation twice, once for each record.

161

MODEL II TRSDOS

Error Conditions

If a TRSDOS error occurs during the patch operation, you will receive the
appropriate * * ERROR nn * * message , and the patch will be terminated without
changing the file.

PATCH can also produce the following messages:

PATCH SIRING

TOOLdNG-

ABORT

FILE CONTAINS

VARIABLE-LENGTH

RECORDS-ABORT

STRING NOT
POUND

ADDRESS OUT OF

PROGRAM-LOAD

RANGE-ABORT

This occurs when you are patchi ng a data file and the
patch string spans two records. You will need to per-
form the patch in two steps, one for each record thai
contains a part of the string to be changed.

You can only patch fixed length record files.

The find-string string was not found at the patch loca-
tion you specified. Before patching a file, you must
know the exact patch location and the existing can-
tents of that Ideation.

This occurs when you attempt to patch a program file,
and some or all of the patch string is outside the ram
area where the program resides when it is loaded.
Check the A^aaaa parameter. Also be sure that the
findstring and changestring aren't longer than you
intended for them to be.

162

UTILITY PROGRAMS

TERMINAL

This is a versatile program designed to allow communications between the
Model II and another computer running a host program, terminal is
designed primarily for transmission and reception of ASCII text rather than
machine-language object code.

Input/output is through serial channel A. In most applications, hookup will
be through telephone lines via a modem.

TERMINAL has three modes of operation:

• Menu — Allows you to select or change options, even execute TRSDOS
library commands

• Interactive terminal — Transmits your keyboard input and displays
incoming data

• Transmit from RAM — For high-speed transfer of prepared data. Incoming
data is displayed on the screen.

Figure 1. A typical terminal/ host configuration.

163

MODEL II TRSDOS

Setting Up

For communications through ordinary telephone lines, you will need a
modem such as the Radio Shack Telephone Interface II, Catalog Number
26-1171, and the Model II RS-232 Cable, 26-4403.

1. Set up the modem according to its instructions, and connect it to
channel A on the back panel of the Model II display console. Unless
channel B is connected to another device, you must install the serial
terminator on that channel.

2 . Find out what RS-232-C parameters are required by the host program you
are going to use:

Baud rate

Word length

Parity

Number of stop bits
You will need to initialize channel A accordingly (see "Running
Terminal").

3 . Set the modem to originate or answer mode — whichever is different from
the mode used by the host program you are going to communicate with.
Also set it to full or half duplex, again depending on the requirements of
the host program.

4. Turn on the modem and the Model II computer system.

MODEL ll

TELEPHONE INTERFACE

Figure 2. Connection of Model II to a modem.

164

UTILITY PROGRAMS

Running Terminal

Since TERMINAL allows you to enter any TRSDOS library command, it is not
necessary to initialize channel A or the printer before starting.

From the TRSDOS READY mode, you can start terminal by typing:

TERMINAL

The program starts up in the menu mode, with the prompt:

— ENTER MENU SELECTION ..

Note: When we show computer prompts and user input in the same example ,
we highlight the user input with a gray background.

Now is a good time to initialize channel A according to the requirements of
the host program you are going to communicate with. Type:

-- ENTER MENU SELECTION S

The program will prompt you to type in a trsdos command. Type in the
SETCOM command just as you would in the TRSDOS ready mode. For
example,

ENTER TRSDOS COMMAND (1-79 )

SETCOM A*(300»7*N»2> (ENTER)
would enable channel A with 300 baud, seven-bit words, no parity and two
stop bits. After executing the command, control will return to terminal's
menu mode.

If you plan to use the printer option of terminal (described later on), you
should also initialize the printer now, with the forms command. Type:

-- ENTER MENU SELECTION S. (ENTER)
and enter the appropriate FORMS command.

To select another menu command, type in the letter specified in the menu
table. For example, type:

— ENTER MENU SELECTION M (ENTER)
to redisplay the entire menu.

165

MODEL II TRSDOS

Modes of Operation

Menu Mode

This is an off-line mode, i.e., you cannot transmit characters to the host
program, and if characters are sent to you, they will be lost. This is the only
mode in which you can select menu options described later on. From it, you can
also enter the transmit from ram or interactive terminal mode.

Interactive Terminal Mode

You can enter this mode from the menu with the T command; you also enter
this mode automatically after completion of an auto sign-on or a transmission
from the RAM buffer.

In the interactive terminal mode, characters you type are sent to the host
program, and incoming characters are displayed as they are received. If the
host program echoes your transmissions, they too will appear on the display;
if not, you can select the echo option and terminal will display your
keyboard input.

Incoming characters can be saved in the ram buffer (R option) and can be
output to the printer (P option).

If transmission errors occur, TERMINAL will display a descriptive error
message and wait for the error condition to be corrected. When it is, normal
I/O will resume in the interactive terminal mode.

To return to the menu mode, press (BREAK)

Transmit from RAM (and Auto Sign-On)

You enter this mode via the X command. The contents of the RAM buffer are
sent to the host program, and control passes to the interactive mode. Auto
sign-on (O command) works just like transmit from RAM; the following
comments apply to both operations.

The RAM buffer contains prepared text which you have typically loaded from
a disk file with the G option. (If you are using auto sign-on, your auto sign on
message is sent.) You can send the data one line at a time when the host
program prompts you that it is ready (W option), or send it in a continuous
stream.

166

UTILITY PROGRAMS

During the transmission, incoming text will be displayed on the screen. If the
host program echoes your transmissions, you will be able to verify that the
data was sent accurately.

During the transmissions, you can adjust the delay between characters by
repeatedly pressing the CD (faster) and fj) (slower) keys. If echoed data
appears garbled, slow down the transmissions. If not, you might want to
speed it up.

If a break character or sequence is received in this mode, TERMINAL will pause until
the next character is received . If a X' 1 3 ' is received , TERMINAL will pause until a
X' 1 1 " is received. (By convention, X' 13' is called the DC3 signal and means
pause; X' 1 1' is called the DCl signal and means resume).

If transmission errors occur, terminal will display a descriptive error
message and wait for the error condition to be corrected. When it is, normal
I/O will resume.

To exit from this mode at any time, press (MEM) . You will be returned to
the menu.

167

MODEL II TRSDOS

Details of the Menu

M Display Menu

After you have entered several menu commands, the menu begins scrolling
off the display. Use the M command to clear the display and redisplay the
menu.

S Perform System Command

Whenever you need to perform a TRSDOS library command, use this
command as shown previously. After execution of a TRSDOS library
command, control will return to terminal's menu.

Some TRSDOS commands and programs always return to TRSDOS READY. Refer to
pages 2/4 and 3/3 for lists . If you execute any of these via the S command , control
will not be returned to TERMINAL, but to TRSDOS READY.

B Set/Change Break Character or Sequence

This command lets you select which incoming code will be interpreted as a

' 'break" . It also lets you define a key to send that same break character or to send a

break sequence.

For the break character, any code from to 255 may be specified. For the break
sequence, any duration from 1 to 451 milliseconds maybe specified. (The correct
time period duration for a break sequence is determined by the host program, and
depends on the baud rate . ) For the user-defined break key , any key except (BREAK)
or (HHDGD may be used .

When TERMINAL receives the specified break character (or whenever it receives a
break sequence), it will warn you so you may take appropriate action. If it is in the
transmit from RAM mode, it will pause the transmission until the next character is
received.

168

UTILITY PROGRAMS

The following example shows how you would set up X'OA' as the break character,

and (CTRDCBD as the break key.
—Enter Menu Selection B (ENUB)
Break Key is Now 1B Hex
Change? (Y/N) Y-dSHE)

Enter New Key (1 ) (GTRDQD Break Key is Now 04 Hex
Type of Break is N owCHR
Change? (Y/N) W (SEE)
Break Char is Now 03 Hex
Enter new CHAR Value in Hex (2) 0A CENTER]
Break Char is Now 0A Hex

The following example shows how you would establish the break sequence and
define (ESC) as a break-sequence key.

—Enter Menu Selection B (ENTER]
Break Key is Now 1B Hex
Change? (Y/N) N INUE)
Type of Break is N owCHR

Change? (Y/N) Y (HUB)
Type of Break is Now SEQ
Break SEQ is 250 mil sees
Change? (Y/N) ft (HUB

W Set/Change Prompt Wait Character

This command affects TERMINAL operation in the transmit from RAM mode
and during auto sign-on. It does not affect operation in the interactive
terminal mode.

The prompt wait feature allows you to use the high-speed transmit from RAM
mode — even when the host program can only accept one line at a time.
Typically, the host program sends you a prompt such as a question mark or
colon when it is ready for the next line. In the interactive keyboard mode, you
would simply wait until this prompt is displayed; the prompt wait feature
makes TERMINAL do the same thing while in the transmit from RAM mode.

When the feature is on, TERMINAL will send one line at a time, and wait for a
prompt character from the host program before sending each line. (A line is
defined as a string of characters terminated by a carriage return X'OD'.)

You can define the prompt wait character as any keyboard character from

X'20'toX7F.

Leave the prompt wait feature off when the host program is simply storing
characters as received, and is not sending a ready-for-next-line prompt.
TERMINAL will transmit text from RAM in a continuous stream.

169

MODEL II TRSDOS

Suppose the host program sends a question-mark (code X'3F') when it is
ready for a line of text. Then type:

-—■ENTER MENU SELECTION W CENTER)

PROMPT OPTION NOW OFF

PRESS ENTER TO LEAVE AS™ IS OR ENTER NEW CHARACTER f

PROMPT OPTION ON WITH >? 7 AS THE CHARACTER

« ENTER MENU SELECTION „.

From now on during auto sign-on or transmit from ram, terminal will wait
for the question-mark prompt before it sends a line.

Note: When you start the transmit from RAM (X option) or auto sign-on (O
option), the first line will be sent immediately, without waiting for a prompt.
Each subsequent line will be sent after a prompt has been received.

To turn the prompt wait feature off, press (HOLD) when the program asks
for a new character.

F Set/Change Fl & F2 Keys

This command lets you program Fl and F2 to output any code from zero to
255. This is useful when you will be using a particular code frequently.

For example, suppose the host program accepts a X'13' as a pause control,
and X' 1 1' as a resume. After receiving a pause character, it waits for a resume
character before sending any more text.

Although you can send these codes from the keyboard ( CTRL Q is a X'll'
and CTRL S is a X'13'), it would be more convenient to program Fl and
F2 to send these codes. Type:

- ENTER MENU SELECTION F (ENTER)

Fl KEY WILL SEND A 01 HEX CODE

CHANGE? (Y/N) Y CENTER)

ENTER NEW CHAR VALUE IN HEX (2) It

Fl KEY WILL SEND A 11 HEX CODE

F2 KEY WILL SEND A . 02 HEX CODE

CHANGE? (Y/N) V CENTE R)

ENTER NEW CHAR VALUE IN HEX (2) 13

F2 KEY WILL .SEND A 13 HEX CODE
- ENTER MENU SELECTION . .

Now when you type (H) in the interactive terminal mode, TERMINAL will
transmit the resume control X'll'; for (ED , the pause control X'13'.

170

UTILITY PROGRAMS

L Toggle Line Feed Option

This command tells TERMINAL how to handle an incoming line feed X'OA'.
When the option is on, all line feeds are ignored. When it is off, they are not
ignored.

The option is useful if the host program always sends a line feed after a
carriage return. Since the TRSDOS display and printer drivers automatically
perform a line feed after a carriage return is sent, the incoming line feed is
redundant. Therefore the line feed option should normally be on.

To toggle (change the state of) the line feed option, type:

— ENTER MENU SELECTION L [ENTER)
The new state of the option (on or off) will be displayed, and the menu
prompt will return.

P Toggle Printer Option

This command turns the printer option on and off. When the option is on,
incoming text will be copied to the printer as it is received and displayed.
Whenever you use D command while this option is on, the RAM buffer text
will be copied to the printer.

Be sure you have initialized the printer with the FORMS command before
attempting to use it.

To toggle the printer option, type:

— - ENTER MENU SELECTION P [ENTER)
The new state of the option (on or off) will be displayed, and the menu
prompt will return.

TERMINAL uses a circular buffer for efficient output to the printer. However,
if characters come in too fast, they will not be printed. They will be displayed,
though, and will be saved in RAM if the buffer is open. (Check your printer's
specifications for maximum character input rate. At 300 baud, 7-bit
characters may come in as fast as 30 per second.)

To minimize hookup time, don't use the printer option while on-line with the
host program. Save the incoming text in RAM instead. After completion of
the hookup, turn the printer option on and use the D command to get a hard
copy of the data.

171

MODEL II TRSDOS

E Toggle Self Echo Option

Some host programs echo the text you send. That is, as the host receives each
character, it sends it right back to you. In this case, what you send will be
displayed on the screen. When communicating with this type of host
program, set your modem to full duplex.

If the host program does not echo your text, then what you send (keyboard
input or text from RAM) will not be displayed. In this case, you should use the
self-echo option, which displays everything you type or transmit from RAM.
With such host programs, set your modem to half duplex.

To toggle the echo option, type:

-- ENTER MENU SELECTION E CENTER)
The new state of the option (on or off) will be displayed, and the menu
prompt will return.

R Toggle RAM Buffer Option

This command pertains to the interactive terminal mode only. It lets you save
in RAM some or all the data that is received, by "opening" and "closing" the
RAM buffer. That way, you can examine the data later with the D command,
or save the data in a disk file with the C command.

Whenever you open the RAM buffer, you have a choice of resetting it or
retaining its current contents. In the latter case, new incoming text will be
loaded after the existing text in the ram buffer.

To toggle the RAM buffer option, type:

— ENTER HENU SELECTION ft CENTER]
The new state of the option (on or off) will be displayed. If you have just
opened the buffer, you will receive the following prompt:

RAM BUFFER NOW OPEN

RESET RAM BUFFER? (Y/N) . .

If you type Y CENTER) , the buffer will be reset and previous contents will be
lost. For further information, see "Using the RAM Buffer."

172

UTILITY PROGRAMS

A Build Auto Sign-On Message

This command lets you prepare an automatic sign-on to be sent to the host
program with the O option. Typically, the message will contain responses to
the standard sign-on questions provided when you first call up a host
program.

The message can be up to 60 characters, consisting of any characters that can
be entered from the keyboard. The message can include control characters.
To embed a carriage return (X'OD') in the message, press (J) . It will be echoed
as — , but a carriage return will be stored.

If you enter any other control character in the message, it will also be
displayed as a + , but the true control code will be sent. (When you display a
message, control codes will not be shown at all.)

For example, suppose the host terminal requires responses to the following
prompts during sign-on:

USER ID?

USER PASSWORD?

PROGRAM NAME?

Instead of typing in information each time you call up the host program, you
can store the responses in an auto sign-on buffer. In this case, the buffer might
contain the following information:

FTW-779 <X'13D'>
LUMMOX <X'0D'>
MENU <X'0D'>

To set up this auto sign-on message, type:

- ENTER MENU SELECTION i (ENTER)

THE CURRENT AUTO SIGN ON IS

CHANGE? (Y/N) Y (ENTERJ

ENTER AUTO SIGN-ON MESSAG E (1 -60)

FTW ® LUMMOX ® .MENU fENTERl

THE CURRENT AUTO SIGN ON IS

FTW

LUMMOX

- ENTER MENU SELECTION ..

The blank line above indicates that the original auto sign-on was blank or
contained non-display characters.

173

Modelll TRSDOS

G Get Disk File into RAM Buffer

This command lets you load text stored in a disk file into the ram buffer.
Then you can send it to the host program via the transmit from RAM
command. The previous contents of the RAM buffer are lost.

The disk file can contain fixed- or variable-length records, and fixed length
records can have any length. However, only ASCII files should be loaded and
sent. You can send basic programs as long as you saved them with the A
(ASCII) option.

For example, suppose you have created a document stored in the file
DOCUMENT/TXT. You want to send it to the host program. To get the file into
the RAM buffer, type:

ENTER MENU SELECTION S CE NTER!

ENTER FILESPEC (1-34)

DOCUMENT/TXT OTTER)
TERMINAL will load the file and return to the menu. The RAM buffer will be
closed.

If the host program is ready to accept data, you can now send it with the X
command. After transmission is complete, TERMINAL will go to the
interactive terminal mode.

C Copy RAM Buffer to Disk

This command creates a disk file copy of the text in the RAM buffer. The new
file will have a record length of one. Use this command to save data that has
been received into the RAM buffer in the interactive terminal mode. To
minimize hookup time, you will probably want to do this after ending the
connection to the host program. Or if the RAM buffer is full, save it in a disk
file, then reset it and re-open it to accept more data.

For example, suppose you have just received a report in the interactive
terminal mode, and you want to save it in a disk file named report. Type:

- ENTER MENU OPTION £ (WW

ENTER FIL ESPE C (i-34)
REPORT fENTER)

The new file will be created (if REPORT already exists, it will be overwritten
with the new data), and the RAM buffer contents and status will be
unchanged.

To stop the copy process, press (BREAK) . The disk file will be closed and you
will be returned to the menu.

174

UTILITY PROGRAMS

D Display RAM Buffer

This command displays the contents of the RAM buffer. To pause the display,

press (HOLD) . To continue, press F2 [HOLD) . If the printer option is on when you issue

this command, the text will also be output to the printer. To enter the

command, type:

— ENTER MENU SELECTION » CENTER)

To stop the display function, press [BREAK) . You will be returned to the
menu.

X Transmit RAM Buffer and Enter Term Mode

This option puts you in the transmit from RAM mode, in which the current
contents of the RAM buffer are sent to the host program. When the entire
buffer haS been sent, TERMINAL goes into the interactive terminal mode. For
details see 'Transmitting from RAM."

To stop transmitting from RAM, press [BREAK) . You will be returned to the
menu.

O Enter Terminal Mode with Auto Sign-On

This command starts transmission of the current auto sign-on message. After
the message is sent, TERMINAL enters the interactive terminal mode. For
details, see "Transmitting from RAM."

To stop transmitting the auto sign-on, press [BREAK) . You will be returned to
the menu.

Note: Most host programs cannot receive anything until the host program
has sent the first prompting message. Because of this, you should:

1. Go to the interactive terminal mode (T option) when connection is first
made, and wait for the host to send its first prompt character.

2. Press [BREAK) to return to the menu.

3. Start the auto sign-on (O option).

T Enter Terminal Mode

This command puts you directly into the interactive terminal mode. While in
this mode, press [BREAK) to return to the menu.

For details, see "Interactive Terminal."

175

Model II TRSDOS

V Toggle Video Filter

Some data characters cause undesirable results when output to the display. For
example, if an ESC (X 1 IB') is output, it clears the screen and homes the cursor.

The video filter option lets you prevent this from happening by "filtering" these
characters from the display. If the RAM buffer is open, they will be saved in RAM,
regardless of the state of this option.

Here is a list of filtered codes when the option is on (all codes are given in
hexadecimal):

01 , 02, 03, 04, 05, 06, 07, 0B, 0C, 0E, OF,
10, 11,12, 13,14, 15,16, IE, IF

If any of these characters is received while the video filter is on , a ' ' ± " will be
displayed in its place.

Q Quit

This command returns control to TRSDOS. Any data in the RAM buffer will be lost
(i.e., you cannot restart TERMINAL and recover it) .

176

Utility Programs

Using the RAM Buffer

The RAM buffer is used to store incoming text (R option) and prepared text
from a disk file (G option) so that it can be sent rapidly. The RAM buffer helps
reduce costly hookup time, by letting you perform time-consuming
operations — preparing data or printing it out — while you are off-line.

Size

For 32K Model II systems, the buffer can contain 1 1 ,493 bytes of text; for 64K
systems, 44,261.

For 32K systems using 300 baud (i.e. , 30 characters per second), it will take
approximately 7 minutes to fill the buffer in the interactive terminal mode ; for
64K systems, 25 minutes.

If the buffer becomes filled during a load from disk (G command) or while
receiving data in the interactive terminal mode, a warning message will be
displayed and the buffer will be closed. If you are loading a disk file, you will
be returned to the menu and the buffer will contain the data that was loaded.
If you are in the interactive terminal mode, normal I/O will continue, except
that it will no longer be saved in the buffer.

Saving the RAM Buffer

When the buffer is filled in the interactive mode (or when you suspect it will
be soon), do the following:

1. Transmit a pause or break control character to the host program.

2. Return to the menu by pressing (BREAK) .

3. Copy the RAM buffer to a disk file (C command).

4. Reset the RAM buffer (R command).

5. Return to the interactive terminal mode (T command).

Opening and Closing the RAM Buffer

Often during interactive I/O, you want to save only portions of the text. The
R command lets you do this. Each time you are about ready to receive some
important data, do the following:

1. Transmit a pause or break control character to the host program.

2. Return to the menu by pressing (BREAK) .

3. Toggle the RAM buffer status. If it is not off, toggle it again. If it is on, you
have the option of resetting it or leaving it as is. To add new data onto the
end of old, do not reset it. To delete old data, do reset it. For details and
examples, see R command later on.

4. Return to the interactive terminal mode (T command).

5 . Direct the host program to resume transmission. The data will now be saved
in the RAM buffer as it is received.

177

Model II TRSDOS

Saving the Options You Have Selected

You can create a customized version of terminal — one which starts up
with the options you have selected. For example, the break character and
key, ( F1 ) and C5) characters and auto sign-on message, could all be saved so
you won't have to set them each time you start the program.

Options which may be saved in a customized program:

• Prompt wait and definition of prompting character

• Definition of break character or sequence from host program and assignment of a
break key on your computer

• (FT) and (F2) characters

• Line feed option

• Printer option

• Self-echo option

• Video filter option

• Auto sign-on option

• Receive into RAM option (not recommended)

• Speed of transmit from RAM and auto sign-on (as set by the ® and ® keys).
Once you find out the maximum rate of transmission the host program can
handle, you'll probably want that to become the default rate.

After selecting the options for your customized version, you use the dump
command to create a new program file. Terminal resides from X'3000' to
X'3FFF\ and its entry point is X'3000\

You must give this customized program a name other than TERMINAL — and
leave TERMINAL in its original configuration. Suppose you want to call your
customized version MINE. Then type:

— ENTER MENU SELECTION B (ENTER)

ENTER TRSDOS COMMAND (1-79)

mm m I ne st frm^mm * end-3fff (mm

Now when you type:

TRSDO S RE ADY
MINE (ENTER)

your customized version of TERMINAL will start.

178

Utility Programs

Sample Uses

To Send a BASIC Program

The program must be stored in an ASCII-format disk file. For example,
suppose you are in BASIC and you are ready to save a program on drive 1 with
the file name SORTDATA. Then type:

>SAVE "SORTDATAU'S A CENTER)

; SYSTEH CENTER)

TRSDOS RE ADY

TERMINAL CENTER)
Once you have set up the modem and initialized channel A as explained
previously, call up the host program and place the telephone handset into the
modem. The modem's ready light should come on, indicating that you are
receiving the carrier signal from the host program.

— ENTER MENU SELECTION T CENTER)

Now go through the necessary sign-on with the program. When you want to
send the BASIC program, press BREAK to return to the menu. (If you want to
use the prompt wait option, select it now.) Then type:

— ENTER MENU SELECTION S CENTER)

ENTER FILESPEC (1-34)

S&RTDATAU CENTER)
Terminal will load the program into RAM. Make sure the host is ready to
receive the program, then type:

— ENTER MENU SELECTION X CENTER)

and the program will be sent to the host. Press BREAK if you want to stop the
transmission for any reason. You will return to the menu. Otherwise you will
go into the interactive terminal mode when the program has been sent.

179

Model II TRSDOS

To Receive a BASIC Program

Suppose you are communicating with the host program and it is ready to send
you an ASCII-format BASIC program. Before telling the host to go ahead, first
go to the menu and type as follows:

— ENTER MENU SELECTION I dHUE)

If the buffer is now closed, repeat the R command and terminal will display
the message:

RAM BUFFER NOW OPEN

RESET RAM BUFFER <Y/N) V [ENTER]

This opens and clears the buffer. Now go back to the interactive terminal
mode (T option) and tell the host to send the program.

After the entire program has been received, press (BREAK] to return to the
menu; then type:

— ENTER MENU SELECTION C CENTER]
ENTER FILESPEC (1-34)

NEWFROS CENTER]

This will copy the BASIC program in RAM into a disk file (we named this one
NEWPROG).

To try out the program, exit TERMINAL and go into BASIC. Then type:

Ready

>LOAD n NENPROG" CENTER]
After the program has loaded, you should examine it to see if it needs
modification to run under Model II BASIC. Pay particular attention to BASIC
statements and functions involving input/output:

• Keyboard

• Video Display

• Line Printer

• Disk Files

180

Utility Programs

Error Conditions

In the interactive terminal mode, transmit from RAM mode, or during auto-
sign on, TERMINAL may detect errors related to the serial transmission. In
such cases, it will display an error message in reverse video (black on white) ; if
possible, it will continue normal I/O.

Here are the messages that may be produced while you are in the interactive
terminal mode:

P
O

Parity error. The received character will be displayed after the reverse

Over-run. At least one character has been received but not picked up

by terminal This will happen if you are in the menu mode while the

host program is sending characters.

Framing error. The received character will be displayed after the

reverse F. Check your setcom parameters to see that they match the

requirements of the host program.

The following messages can be produced in any mode except the menu:

DATA CARRIER LOST
DATA CARRIER RESTORED

BREAK SEQUENCE RECEIVED

Check the telephone/modem connection.
terminal will pause until the carrier is re-
stored. If terminal was transmitting from
ram or sending an auto sign-on, it will start
over at the beginning of the text when the
data carrier is restored.

If the host program sends a break
sequence, or sends terminal's own
break character, this message will be dis-
played; if terminal is in the transmit from
ram or auto sign-on mode, it will pause
until the next character is received from
the host

181

Model II TRSDOS

TERMINAL: A Quick Summary

Feature/

Transmit From ram

Interactive

Option

& Auto Sign-On

Terminal

Return To Menu

n/a /:/:;:■:;;/;;

Yes

With (BREW

Execute

Use"S"

TRSDOS

Command

Commands

Break Character

Use"B"

When Break Sequence Or

Transmits

&Key

Option

Break Is Received, Pauses

Character From

Transmission until next

Keyboard

Character Is Received

Wait For

"W"

Yes

Prompt

Option

Program (Ft)

"F"

Yes

And(F2)

Option

Ignore Line

"L"

Yes

Feeds After

Option

Carriage

Returns

Output To

"p"

Yes

Printer

Option

Self-Echo

Use "E"
Option

Yes

Receive Into

"R"

Yes

RAM

Option

Auto

Set Up'

Active Here

Enters This Mode

Sign-On

With "A"
Option; Send
With "0"
Command

When Done

Video Filter

"V"
Option

Yes

■■Yes/-;

Continued on next page

182

Utility Programs

TERMINAL: A Quick Summary, continued

Feature/

Transmit From RAM

Interactive

Option

& Auto Sign-On

Terminal

Get Disk

"G" ■■'■.-.".: ■

File Into

Command

Ram

Copy Ram To

"C"

Disk

Option

Transmit ;

"X"

Active Here

EntersThis

Ram Buffer

Option

Mode When Done

Recognize

Yes

DC1/DC3

Resume/Pause

Display

"0"

Ram Buffer

Command

Adjust Speed

Yes, With GD And (D

Of Transmit

Redisplay

"M"

Command

Save

"S"

Customized

Command

Program

Dump

X'3000'

X'SFFF'

183

Model II TRSDOS

Hal

XFERSYS

Transfer, Modify or Upgrade System Files

XFERSYS :ct {option}

: tf Specifies the cfriw con Wning the destination diskette. If

§ ff no ^ptei is given, fljll is used (see below).

option may M om of the following {these are summaries; details
airegiveii later In this section):

full ItHs fflSDOS to purge all conflicting system files from the

toth^

M.W; te#s^
diskette ariJ ?^eopy only the minimum system from the source
to^

_^_ ... ...

XFERSYS is a multi-purpose utility allowing various system file operations. Here is
a summary of its major purposes:

1. Conversion

Older version (l . l and 1 .2) system and data diskettes must be converted before
they can be used under the 2.0 system.

2. Creation of Minimum System or Data Diskettes

For definitions of "minimum system" and "data" diskettes, see Section Oof
this manual.

3 . Merging System Files from Different Diskettes

This is useful for combining different system language packages onto a single
diskette.

4. Relocating System Files

XFERSYS allows you to create full or minimum system diskettes on which the
directory and system files are moved to a non-standard area of the diskette.

Now we will describe each of these operations in detail, one at a time.

184

Utility Programs

Conversion

The diskette format used by TRSDOS 2.0 is different from that of previous versions.
All earlier-version diskettes, both system and data, must be converted before they
can be used by TRSDOS 2.0.

Follow this procedure for converting your older version diskettes,

1. Make backups.

Reset the Computer and insert the old version of TRSDOS . Use this version to
make a backup copy of all the diskettes that you plan to convert to the new
version. Keep each backup copy in a safe place until the conversion is complete
and confirmed by use. THIS IS VERY IMPORTANT.

2. Check free space map.

Note: This step only applies if the destination diskette is going to contain a full
or minimum system. Skip this step for all data-only diskettes.

Using the older version of TRSDOS , examine the free space map of each of the
diskettes.

TRSDOS 2.0 requires seven tracks immediately following the directory . Any
diskette that has these seven unused tracks following the directory (usually
tracks 45-5 1 ) may be converted as-is.

Any diskette that does not have these seven free tracks cannot be converted until
the files located on these tracks are moved or killed. You should try to copy the
files onto another less-full diskette, then kill the files from the diskette you are
converting. If you don't know which files are stored on these tracks, then
continue with Step 3 . XFERSYS will list exactly which files need to be removed.

For the same reason, there should be no flawed tracks on these same seven
tracks. If there are any flaws, you must backup the diskette onto another one
which has no flaws in this area.

Note: If the 1 . 1 or 1 .2 diskette has the TRSDOS system on it, then tracks 45-48 will
usually be allocated to TRSDOS files . You do not have to move these files , since
XFERSYS will automatically delete them. However, if user files are allocated to
tracks 49-5 1 , these must be moved .

3 . Reset the Computer and insert your 2.0 working master created according to the
instructions in Section of this manual.

Note: The working master contains only those system files that you use from
day to day. The more system files on your master, the longer the XFERSYS
operation will take, and the greater the chance that XFERSYS will be aborted due
to limited disk space.

185

Model II TRSDOS

4. Conversion Step.

4-A. If you want the destination diskette to have a full system, use this command:

XFERSYS :d

where dis the drive which will contain the destination diskette. Multi-drive
users should always use drive 1 , 2 or 3 , since no disk swaps will be required .
Single-drive users must use drive 0; XFERSYS will prompt you to swap
diskettes whenever required. Remember: the SOURCE diskette is your 2.0
working master; the DESTINATION diskette is the one you are converting.
4-B . If you want the destination diskette to have a minimum system diskette, use
this command:

XFERSYS :d MIN

where dis as explained in step 4-A.
4-C. If you want the destination diskette converted to a non-system data diskette,
use this command:

XFERSYS :d DATA
where d specifies the destination drive, either 1 , 2 or 3.

5. XFERSYS runs in three phases (detailed below). The screen will show which
phase is in progress. The complete conversion may take up to 10 minutes,
depending on the number of system files on your source diskette .

If there are not seven contiguous free tracks following the directory, XFERSYS
will list the files that must be moved to free up this area.

In this case, XFERSYS will terminate without making any changes to the
destination diskette. Write down the file names listed. Reset the Computer,
insert the older version of TRSDOS, and kill the files listed by XFERSYS (make
copies first unless you don ' t need them ! ) . Then start over at step 3 .

6. If the conversion is successful, the message CONVERSION COMPLETE will be
displayed. The resultant (destination) diskette is now a TRSDOS 2.0 full system,
minimum system or data diskette, depending on the option selected.

Creation of Minimum System or Data Diskettes

XFERSYS can also take a 2.0 diskette and remove some or all system files to create a
minimum system or a data diskette . Conversely , it can add some or all system files
to a data diskette. The steps are exactly like those described previously, except:

• The entire operation is performed under TRSDOS 2.0.

• There is no conversion phase .

• You may use ANALYZE to determine which files (if any) need to be moved.

186

Utility Programs

Merging System Files

There are times when you want to move the system files from one diskette onto
anot her — without eliminating the system files already on the destination diskette.
Suppose, for example, you have two Radio Shack language packages on separate
diskettes, and you want to combine both packages onto a single diskette. XFERSYS
can accomplish this via the FULL option .

Look back at the syntax block at the opening of this section. Compare the
descriptions given for the three options . Notice that the FULL option purges only
conflicting system files from the destination diskette, but leaves other system files
alone. This feature is what allows the merging of system files.

Note: "System' ' files can be identified by looking at the ATTRB column in the
directory listing. All system files will have the "S" attribute.

1. Backup the destination diskette.

2. Type in the command:
XFERSYS :d FULL

where d is the drive number for the destination diskette.

First XFERSYS will purge from the destination diskette all system files that are
duplicated on source diskette. It will not purge the system files unique to the
destination diskette (i . e . , the language-package files) .

Next XFERSYS will copy all system files from the source. This includes all of the
standard TRSDOS files on the source plus the language files which have the ' ' S ' '
attribute in the directory listing.

Note: Do not attempt to merge and perform a conversion at the same time. Do the
conversion first and then you may merge.

Relocating System Files

For general applications, the standard location of the TRSDOS directory and system
files is most efficient. Each time you use BACKUP to duplicate a system diskette, the
system location is preserved. (In fact, the entire destination diskette becomes a
sector-for-sector duplicate of the source.)

However, in special cases, you might want to locate the directory and system files
in some area other than tracks 44-5 1 . For example , by putting this system
information on tracks 1-8, you leave the rest of the diskette as a single extent. If your
application involves the creation and maintenance of a single data file, this
arrangement might be desirable .

187

Model II TRSDOS

Follow this procedure for moving a full or minimum system to a non-standard area:

1 . Use FORMAT to initialize a diskette with the directory in the desired location.
For example:

FORMAT \d DIR = 1
where d is the destination drive, would place the primary directory on track 1 .

2. Now you use XFERSYS to transfer a full or minimum system onto the formatted
diskette from Step 1.

2-A. Full System. Use a command like this:

XFERSYS :d FULL

where d is the destination drive, will move a full system onto the destination
diskette. The system files will occupy tracks 2-8.

2-B . Minimum System. Use a command like this:

XFERSYS : d

where dis the destination drive, will move a minimum system onto the
destination diskette. The system files will occupy tracks 2-8.

Details of the XFERSYS Process

XFERSYS has three phases.

Phase 1, Parti:

XFERSYS determines whether the diskette is in the current (2.0) format or in an
earlier (1 . 1 or 1 .2) format. If it is in the current format, XFERSYS skips to Phase 1 ,
Part 2 described below.

If the diskette is in an earlier format, XFERSYS removes the old system files. Next it
converts the diskette to the current format. But before this is done, XFERSYS must
make sure there are seven unused tracks immediately following the directory on the
destination diskette. If there aren't, XFERSYS will display the message,

The following must be killed or moved

and then list the files which are ' 'in the way ' ' . Then TRSDOS will cancel the
operation, leaving the diskette unchanged.

188

Utility Programs

Phase 1, Part 2

If ' 'Full" option and destination disk is:

1.1 or 1.2 2.0

TRSDOS kills certain TRSDOS kills only

system files which do those system files

not work under 2.0. whose names are in

the source diskette's

directory.

If the 'FULL' option is not used, TRSDOS kills all system files on the destination
diskette (whether it is a 1 . 1 , 1 . 2 or 2 . 0) .

Phase 2

TRSDOS now copies the system file SYSTEM/SYS. This is the file residing on seven
contiguous tracks following the directory.

Phase 3

TRSDOS copies the remaining system programs (marked with an "S" in the
directory-listing attribute column). The more system files on the diskette, the
longer the XFERSYS operation will take.

Note: If the XFERSYS fails after the diskette has been partially modified, you will
get the message

INCOMPLETE Conversion

The diskette will be unusable. Make a backup from your "safe copy" and start
over.

189

Model II TRSDOS

BASCOM (BASIC Program)
COMSUB (USR Subroutine)
DOCOM (TRSDOS DO-File)
Serial I/O Demonstration

BASCOMnn

is thenar 32 for 32K computers; /m= 64 for

64K computers.

COMSUBrt/T

is the name of the USB subroutine; nr? = 32 or 64 as above.

Docoynn

is the name of a trsdos DO-f ile that automatically initializes channel A for serial
I/O , loads comsub/?/? and starts basic; nn = 32 or 64 as above.

The BASIC communication program BASCOM and the communications
subroutine COMSUB together perform a "terminal" function, demonstrating
an application for Model II's serial interface. The programs are provided to
give you a feel for interfacing programs at the assembly-language level with
BASIC programs. BASCOM calls the machine-language COMSUB via the USR
function. Like TERMINAL, BASCOM and COMSUB are included on your
system diskette and may be examined by employing the trsdos command
LIST (or the BASIC command list in the case of BASCOM).

The programs allow you to use the keyboard of the Model II to send data in
the form of ASCII characters to another computer or device; at the same time,
characters transmitted on the other device will be received by the Model II
and printed on the Display.

Serial channel A is used for sending and receiving. (You must put a terminator plug
on channel B . ) The programs alternately check channel A for a character received,
and the keyboard for a character typed. Characters typed will be automatically
echoed to the Video Display, though this can be defeated by making a two-byte
modification to COMSUB; the NOPs at X^FQF 1 and X'6FA(T (COMSUB32) or X'EF9F'
and X'EFAO' (COMSUB64) should be modified to a LD (HL), 00.

190

Utility Programs |yfii

Sample Use

Before using the two programs, make sure that channel A is connected to a
modem and that channel B is fitted with the serial terminator or connected to
some other serial device (e.g. , a serial printer). Then, under TRSDOS ready,
type:

DO DOCOM32
or
DO DOCOM64

depending on whether you have a 32K or 64K computer. DOCOM32 and
DOCOM64 name DO files which

1. Execute the SETCOM command (parameters are set to default values)

2. Load the appropriate COMSUB subroutine

3. Load BASIC and reserve enough memory for COMSUB. When the BASIC
prompt appears on the screen, type:

RUN "BASCOM32"
or

RUN "BASCOM64"
The program will load and begin.

Error Handling

When a transmit or receive error is detected, COMSUB will print the word
ERROR followed by an 8-bit error code. The leftmost digit represents bit 7;
the right-most digit, bit zero. (The program will continue to attempt serial
I/O.)

If bit 3 is on, then the modem carrier was lost. Check the telephone
connection and all other connections.

If bits 0, 1, and 2 are all off, the error will be a receive error. See ARVC, page
4/78 in the TRSDOS manual, for further details on the error code.

If bits 4, 5 , 6, and 7 are all off, the error is a transmit error. See ATX, page 4/79
in the TRSDOS manual, for details.

Source Listing of COMSUB

The following fully commented listing is provided to aid assembly-language
programmers in writing their own serial I/O routines.

Notice that the program is ORGed at X'EF80'. This is an appropriate address
for 64K machines. For 32K machines, use a start address of X'6F80\

191

Model II TRSDOS

1
t

SUBROUTINE FOR
THIS ROUTINE MUST

8A.SIC COMMUNICATIONS PROGRAM

BE EXECUTED AT 3 00 BAUD flR HTrtHFR

ORG
INC

0EF80H
DE

ION ENTRY DE POINTS TO A 3 BYTE STRING DESCRIPTOR
IDE NOW POINTS TO LSB OF STRING ADDDRESS

LD
LD
INC

A,(DE)
L.A

ILSB OF STRING ADDRESS TO ACCUMULATOR
ILSB OF STRING ADDRESS TO REGISTER L
IDE NOW POINTS TO MSB OF STRING ADDRESS

LD
LD

A, (DE)

H,A

A , ( HL )

(MSB OF STRING ADDRESS TO ACCUMULATOR
tMSB OF STRING ADDRESS TO REGISTER H
M BYTE STRING TO ACCUMULATOR

CP
JR
LD

NZ, XMITER

A ,96

I SEE IF CHARACTER IS ZERO

(IF NOT ZERO TRANSMIT CHARACTER, ELSE FALL THROUGH TO RECIEVE CHARACTER

(SVC CALUPORT A RECIEVE

RST

RET

C , E RROR

IQUIT ON ERROR IF MODEM CARRIER NOT PRESENT
(RETURN IF NO CHARACTER RECIFVEO

OR
JR
LD

NZ, ERROR

{HL),B

ISET STATUS BITS

(QUIT ON ERROR IF ANY STATUS BITS ARE SET

(PASS RECIEVED CHARACTER TO STRING LOCATION

RET
XMITER LD

B,A

(CHARACTER TO BE TRANSMITTED TD RFGTSTFR R

LD
XMITl LD
RST

DE,0FFFFH

A, 97

ILOOP COUNT IF TRANSMITER BUSY STATUS ENCOUNTERED
ISVC CALL»PORT A TRANSMIT

NOP

C t ERROR

IQUIT ON ERROR IF MODEM CARRIER NOT PRESENT

(INSERT -"LD (HL),00 JI HERE WHEN USING MODEM IN HALF-DUPLEX MODE

RET
BIT
JR

0,A

NZ, ERROR

(RETURN IF CHARACTER TRANSMITTED
1 CHECK CLEAR TO SEND STATUS BIT
IQUIT ON ERROR IF STATUS BIT SET

ERROR

8 1 TEST

OR
DEC

LD
LP

BIT

A,D
E

NZ, XMITl
<HL),00
P,8

IMSB OF LOOP COUNT TO ACCUMULATOR
ILSB OF LOOP COUNT
I REDUCE LOOP COUNT

HL,BITST3

7 ? A

(HL) . '0 J

(LOOP IF COUNT IS NOT ZERO, ELSE FAL L THROUGH i O AN ERROR
(DO NOT DISPLAY CHARACTER IF ERROR ENCOUNTERED

(LOOP COUNT (8 BIT STATUS BYTE)

(STORAGE AREA "

ICHECK BIT 7 OF ACCUMULATOR FOR COMMUNICATIONS STATUS

BITST3

INC

RLCA

Z,BITST1

(HL)

(JUMP IF STATUS BIT NOT SET

IASC-II ZERO -> ASC-II ONE IF STATUS BIT SET

I ROTATE ACCUMULATOR LEFT

INC

DJNZ

BITEST

HL t BITSTP

(MOVE TO NEXT STORAGE POSITION
(LOOP TO CHECK STATUS OF 8 BITS
IFPRTIR MFCKA^F Tn RF HTc:PI AVPH

LD
LD
LD

B f 1 A
A, 9

(LENGTH OF MESSAGE

(CHARACTER TO BE INSERTED AT THE END OF ERROR MESSAGE

ISVC CALLIVIDEO LINE

f*ST
RET

BITST2
BITSTJ

DEFM
DEFS

4 ERROR* «
8

(ERROR MESSAGE

ISTORAGE AREA FOR ERROR STATUS BITS TO BE DISPLAYED

192

Utility Programs

DATM (Machine-Language Subroutine)
EXDATM (Console Program)
Date Calculations

DATMH/7

is a machine-language subroutine that performs date calculations; nn = 32
for 32K computers; nn = 64 for 64K computers.

EXDATy/7/7

is a console program (can be executed from trsdos ready mode) that loads
and uses OATUnn; nn = 32 or 64 as above.

EXDATM is a console routine which calls the date calculation program DATM
and allows you to pass data to it from the keyboard.

DATM performs two functions:

1. Given a date and a timespan measured in days, the program adds the
timespan to the date and calculates the resulting date. The timespan can't
be greater than 65535 days; the year of the date must be at least 1600 and
not larger than 9999.

2. Given two dates, the program calculates the number of days between the
dates. The same parameter limitations apply.

Sample Uses

Under trsdos ready, type:

EXDATM64
or

EXDATM32
depending on whether you have a 64K or 32K machine. The program will
ask you:

DATE ADDITION OR DIFFERENCE (A/D) ..

Date Addition

To add a date and a timespan, type:

a 115113

The program will ask:

ENTER PARAMETERS

to which a sample reply might be:

05/14/1977 0018!? ^ffl
The program will compute and print the date which is 180 days after May
14, 1977:

THU NOV 101977314
followed by the system time. The number 314 means that November 10 is
the 314th day of 1977 (see the TRSDOS date command).

193

Model II TRSDOS

In general to find a new date from a date and a timespan, the date and
timespan should be entered like this:

mm/dd/yyyytijjjjj
where mm is a two-digit number 01-12; dd 7 a two-digit number 01-31;
yyyy, a four-digit number 1600-9999; and////; (Julian measure of time), a
five-digit number 00001-65535. (Julian time refers to the measure of time
in days rather than hours, years, months, etc.) Be sure to use leading
zeroes as required to make up the specified number of digits. And don't
omit the space (#) between yyyy and;;;;;.

Date Difference

To find the number of days between two days, type D B5I13 in
response to the initial prompt (A/D). In response to the enter
PARAMETERS prompt, type in your data as in this sample:

04/15/1979 12/31/1979 BSH
The program will print the number of days between the dates you entered:
625.

In general to find a timespan between two dates, the dates should be entered

like this:

mm/dd/yyyyftmm/dd/yyyy

where mm is a two-digit number 01-12, dd, a two-digit number 01-31; and
yyyy, a four-digit number 1600-9999. The earlier date must come first.
Since the maximum timespan that can be returned is 65535 days, the two
dates must not be separated by more than 179 years. Use leading zeroes
where necessary to make up the specified number of digits, and don't omit
the space Q6) between the two dates.

194

Utility Programs

DATM Source Listing

For Assembly-Language Programmers

Notice that the program is ORGed at X'OOOO' . This is simply to make it easier for you
to relocate the program, DATM32 is actually ORGed at X'6C60'; DATM64, at X'ECW .

In general, the entry and exit conditions for this subroutine are the same as
those given for EXDATM.

Entry Conditions

B = Function Switch

If B = then compute date addition

If B ^ then compute date difference

For date addition (B = 0)

(HL) = 16-byte text buffer located above X77FF, as follows:

mmlddlyyyyfyjjjj

just like the input text for exdatm described previously.

(DE) = 26-byte output buffer located above x'27FF\ as follows:

NAME OF MONTH DAY OF
DAY MONTH

YR.

DAY OF
YR.

TIME

MONTH DAY OF
OF YR. WEEK

For date difference (B ^ 0)

(HL) = 21-byte text buffer located above X'27FF, as follows:

mm/dd/yyyytymm/dd/yyyy

just like the input text for exdatm described previously.

(DE) = 5-byte output buffer, located above X77FF, as follows:

jjjjj.

with leading blanks supplied as necessary.

To call DATM, execute a CALL to the start address.

Exit conditions

(DE) = output text, in the format described previously.
NZ = Error occurred
A = Error code

195

fModelllTRSDOS

DATM
OBJ CODE M STMT SOURCE STATEMENT

12/1 0/79 — 1 5:00

PAGE 1

ASM 5.8

0000
0001

0002

E5
05
C5

0003

0004

7C
FE28

2
_3__

5
.___.&__

9
10
1 1
J 2_
13
1 4
15

1 6

1 7
1 8

19
20
21

_24__

_.2Z._

31"

JULIAN DATE MATH ROUTINE

B=FUNCTION SWITCH

IF B~7. THEN MM/DO/Y.YYY + JJJJJ-NEW DATF

IF B=NZ THEN MM/ DO/ Y YYV-M M/ m/Y YYY* JJJJJ

..ENTRY ,1 DE~>26 BYTE OUTPUT FIE LD (SEE SYSTEM DATF ROUTINE)

HL=>MM/DD/YYYY JJJJJ

MM=MONTH
DO=DAY

YYYY=YEAR (16 00 <= YYYY <- 9999)
JJJJJ-JUL IAN TI ME S P AN IN DAYS (JJJJJ

655 3 5) .

3=NZ ENTRY

X DE^>5 BYTE OUTPUT FIELD (JJJJJ)

. ... HL~> MM /DP/ Y Y YY MM /DO/YYY Y (EARLIER DA TE. LATER D ATE)

EXIT

* A=Z GOOD INDICATION

A-N Z A CO NTA INS E RROR CODE

FOR 64K VERSION RELOCATE AT EC60H
JZD«_3^K_..y_ERSI0N REL OCATE AT ___&C6&H_

35
36

PUSH
PUSH
PUSH

HL
DE
BC

(SAVE CALLER'S REGISTERS

;

38
39

LD
CP

A,H
28H

(CHECK FOR BAD BUFFER ADDRESS

0006

0008
0009

000b
0000

0011

38 22
7A

FE28

40
41
42

LD
CP

38 ID
ED538101 R

C f ERROR

A,D

28H

0012

0013

0016

43
44
45

(QUIT ON ERROR

I CHECK FOR BAO BUFFER ADDRESS
_! . ^^___^^

JR C .ERROR (QUIT ON ERROR
LD (OUTDSS),DE (SAVE OUTPUT BUFFER POINTER
_XOR A (ZE RO A CCU.

0019
001 B
00 ID
001 E"
0020
002 1
~ m23~

mzA

0028

C2A102 R

C D2E02 __R_

200F

3E20

2 00A

3E 15 __

ED532702 R
2807

48 __J_ULDAT_

49 "
50
51

~52 "
53
54
55
56
57

CP
JP
CALL

JR
LD
CP

NZ t TWODAT

EDI T

NZ, ERROR

A, f *
(HL)

(LOOK AT OPTION SWITCH

( ACT HN OPTION

(EDIT INPUT

(QUIT ON ERROR
(BLANK
(CHE CK BLANK

NZ, ERROR

(QUIT ON ERROR

INC

(BUMP INFORMATION POINTER

A 4 1 5H

(CONVERT

RST

002A

3E03

58 ERROR

(JUL! ),DE
Z, JULT

(SVC

(SAVE JULIAN SPAN

(QUIT ON ERROR

A, 3

(PARAMETER

196

Utility Programs "iaGr*

LOC

08J CODE

STMT

DATM
SOURCE STATEMENT

12/10

/79--15J00 PAGE 2
ASM 5.8

002 C
002 D
002E

87
CI
01

59
60
61

ALEX IT

POP

ISET FLAGS
(RESTORE REGISTERS
*

002H
0030

LI
C9

63
64

POP
RET

» RETURN TO CALLER

0031
0034

0037

CDF601
3 A 22 02

1600
5F

210101
19

R
R

65
66
67
68
69
70

JULT
AGAIN

CALL

FIXFE8
A, (M0N1 )

D,0

(LEAP YEAR ?
;get MONTH

I ZERO MSB

0039

003 A
0030

LD
LD
ADO

E,A

HL, MONTHS

HL , DE

(move month

(month table

(find month in table

003E
003F

0042

2A2702

71
12
13

LD
XOR

E , C HL )
HL, (JUL1 )
A

(DAYS IN MONTH

(JULIAN SPAN

(CLEAR FLAGS

0043
0044
004 6

1 3

ED52
23

74
75

INC
SBC
INC

HL,DE

(ADJUST FOR COMPARE

(REDUCE COUNT BY MONTH'S LENGTH IN DAVS

(READJUST REMAINING SPAN

0047
0049

004C

3011
2A2702
3 A 23 02

R
R

77
78
79

LD
LD

NC,NOTYET
HL, (JUL1 )
A, (DAY1 )

(JUMP IF OVER MONTH'S LENGTH
(JULIAN SPAN
(DAY OF MONTH

004F
0050
0051

ED52

382A

" sw

81
82
83
84
85

ADO

SBC

INC

XOR

A,L
L,A

HL . OE

(ADD DAY OF MON T H TO SPAN

(MOVE SPAN

(SEE IF OVER A MONTH

0053
0054

0056

C, FINISH
A

(READJUST REMAINING SPAN

(LEAVE LOOP IF NOT OVER A MONTH

I7FR0 ACCU. - -

0057
005 A
0050

3223id2
222182
21 22id2

R
R

86
87

NOT YET

LD
LO
LD

(DAY1 ) , A
( JUL1 ) ,HL
HL , MON 1

(ZERO DAY OF MONTH TO GET OUT OF LOOP
(SAVE LOOP COUNT
(ADDRESS OF MONTHS

0060
0061
0062

34
7E

FE0D

89
90
91

INC

(HL)
A, (HL)
13

(BUMP MONTH
( GET MONTH
( 1 3 MONTHS

0064
0066
0068

38D1
06 0C
77

92
93
94

SUB
LD

C, AGAIN

1 2
(HL) ,A

(LOOP ON CARRY
( ADJUST MONTH
(SAVE MONTH

0069
006C

006D

212102
34

FE64

388F

D664

212002

R
R

95
96

97
98
99
1 00
101
102
103

INC
LD

HL,YR1
(HL)
A , ( HL )

(YEAR ADDRESS
(BUMP YEAR
(GET YEAR

006E
0070
0072

SUB

INC

1 00

C ,JULT

1 00

(HL) ,A

HL,CEN1

(HL)

( 1 00 YEARS
(LOOP ON CARRY
_LADJUST YEAR _ _ __ _

0074
0075
0078

(SAVE YEAR

(ADDRESS OF CENTURY

(BUMP CENTURY _ .. _ ... _

0079
007A
007C

FE64
28AC

104
J 05
106

(

FINISH

A , ■( HL )

i m

Z. ERROR

(GET CENTURY
(SEE IE 7FR0
__ LQULI QN,..£RRQR_ - __ __ _

007E
0080

18B1

3223&2
6f-

26 00
11D101

R
R

107
108
109
110

I 1 1

II 2

LD~"

ADD

JULT
(0AY1 ) ,A

(LOOP

(SAVE DAY OF MONTH

0083
0084
0086

L,A

H,0

DE, MONTHS

A,( M0N1 )

B,A

A , ( DE )

A,L

(MOVE IT
(ZERO MSB
(MONTHS TABLE

0089
008C
0080

3A22H2
47
1A
85

113
11 4
115
1 1 6

NEXT1

( MONTH

(MOVE IT

(DAYS IN MONTH

008 E

(ADD UP JULIAN DAYS

197

Model II TRSDOS

DATM
OBJ CODE M STMT SOURCE STATEMENT

12/1 0/79 — 15:00

PAGE 3

ASM 5.8

ma?

3 00 J

117

NC t NEXT2

(JUMP IF NO CARRY

0091

118

INC

(BUMP MSB

0092

119 NEXT2 LD

L,A

(MOVE LSB

0093

120

INC

(BUMP TABLE ADDRESS

0094

10F7

121

DJNZ

NEXT1

iLnnp

0096

21147)2

1 22

(JULIAN) ? HL

(SAVE JULIAN DAYS

123 (

0099

218A01

124 L08UFF LD

HL,TABLX

; LENGTH TABLE

009C

229301

J25

(TABORS) ,H1

ISAVF TARi E ADORF^

009E

212002

126

HL,CEN1

(ADDRESS OF CENTURY

00A2

127

L , ( HL)

; CENTURY

00A3

0E64

128

C,1 00

1*1 00

00A5

06 00

129

B,0

I MULTIPLY PARAMETER

00A7

130

H t B

IZERO H

0tfA8

3E17

131

A, 1 7H

1 MULTIPLY

00 AA

132

RST

(SVC

00A8

3A2102

133

A,( YR1 )

;GET YEAR

00AE

1600

134

D t

( ZFRn MSB

0060

135

E,A

IMOVE YEAR

0081

136

ADO

HL,DE

I GET TOTAL YEAR

0082

114006

137

DE, 1600

(BASE YEAR 1600

00B5

138

(ZERO CARRY

008 6

E052

139

SBC

HL,DE

(YEARS SINCE BASE

00 88

1 40

PUSH

(SAVE YEARS SINCE BASE

0089

0601

141

B,l

(DIVIDE PARAM

0088

0E04

142

C,4

t/4

008D

3E17

143

A , I 7H

(DIVIDE

00BF

1 44

RST

(SVC

00C0

145

INC

(ADJUST FDR DAY ZERO SAT->MON

00C1

1 46

INC

(SAME

00C2

147

INC

(SAME

00C3

148

INC

(SAME

00C4

149

INC

(SAME

00 C5

150

PUSH

(SAVE MOD 4 YEARS

00C6

3A2 002

151

A , (CEN1 )

(GET CENTURY

00C9

0610

152

SUB

1 6

(BASE CENTURY

00CB

153

PUSH

(SAVE DIFFERENCE

00 CC

154

L,A

(MOVE DIFFERENCE

00CD

2600

155

H.0

IZERO MSB FOR DIVIDE

00CF

0E04

1 56

C,4

1/4

00D1

3E17

157

A, 1 7H

(DIVIDE

mo 3

158

RST

1 SVC

0004

F.I

159

POP

(DIFFERENCE

00D5

160

SUB

(SUB # OF OUADRENNIALS

00O6

161

L t A

(MOVE ADJUSTMENT FOR CENTURY

00D7

1 62

PUSH

(SAVE ADJUSTMENT

00D8

CODE 01

163

CALL

LPORNT

(DETERMINE PROPER ADJUSTMENT (LEAP OR NOT)

mos

1 64

POP

(ADJUSTMENT

00OC

2 001

165

NZ,UPDAT3

(NOT QUADRENNIAL

000 E

1 66

INC

( INC ADJUSTMENT

00OE

167 UP0AT3 EX

DE,HL

(ADJUSTMENT TO OE

00E0

1 68

POP

(MOD 4 YEARS

00E3

169

XOR

(ZERO FLAGS

00E2

ED52

1 70

SBC

HL.DE

(ADJUST MOD 4 YEARS

00E4

171

DE.HL

(MOD 4 YEARS TO DE

00E5
00E6

00E7

El
19

172
173

POP
ADD

HL
HL,DE

(TOTAL YEARS

(TOTAL DAY S OFF FROM BASE TO YEAR IN ?

ED5B2402 R 174

DE, (JULIAN)

(GET JULIAN DAY

198

Utility Programs

LDC

D3J CODE

DATM
M STMT SOURCE STATEMENT

12/1 0/79 —

-1 5:00 PAGE A
ASM 5.8

00EB
00EC

0E07

0601

175
176
1 77

ADO
LD

HL,DE
C,7
3, J

(ADD JULIAN DAYS

1/7

(DIVIDE PARAM

00F0

00F2

3E1?

21 2602

178

1 79

1 80

LD
RST

A,1 7H

HL, WK1

(DIVIDE

(SVC

(DAY OF WEEK _. _

00F6
00F7
0.0F9

0600

2A8101

181
182
183

LD
LD

( HL ) , C

8,0

HL, (OUTDSS)

(SAVE ABOVE

;DATE PARAMETER

(OUTPUT BUFFER ADDRESS

00FC

W0FE
00 FF

3E2D

C22A00

1 84

185
186

LD
RST

A,2DH

NZ, ERROR

(DATE

(SVC

(QUIT ON ERROR

4102
0105
0106

219501

C807

187
1 88
189

LD
LD
RLC

HL,NAMDAY

A,C

(GET DAY OF WEEK TABLE

(MOVE DAY OF WEEK

(DOUBLE IT _ . __ -

0108
0] 09
01 A

81
85

190

191
192

ADD
ADD
LD

A,C
A,L

L,A

(TRIPLE IT

(ADD TABLE ADDRESS

(FIND TABLE ADDRESS _. . .

0106

0L0D
01 0E

3001

010300

193
194
195

OAYOFW

JR
INC

NC ,DAYOFW

8C,3

(JUMP IF MSB NC

( BUMP MSB ON C

1 3 LOOPS .... . _ .

01 1 1
0114
01)7

CD 8 0.01
3 A 22 02
21 AA01

R
R
R

196
197
1 98

CALL

LOADSS
A , C M0N1 )
HL.NAMONT

(LD BUFFER
(GET MONTH
(GET TABLE _ ._. - _ _

011A
01 18
01 10

CB07

199
200
201

RLC
ADD

8 t A

A,B

(MOVE MONTH

(DOUBLE IT

(TRIPLE IT _ . .

011 E
01 IF
0120

85
6F

3001

2<A2
203
204

ADD

A,L
L ,A

NC,MQNOFY

(ADD TABLE ADDRESS

(FIND TABLE ADDRESS

(JUMP IF MSB NC ... .....

0122

0123
0126

24
0i0300

COS 001

205
206
207

MONQFY

INC

CALL

BC,3

LOADSS

( INC MSB ON C

(3 LOnPS

(LOAD BUFFER . ...„ ... ...... - -----

0129
012C
01 2F

3A2302

CD5D01
3A2002

R
R
R

208
209
21

CALL

A, (DAY1 )
CONSUB
A T (CEN1 )

( GET DAY

(CONVERT

tGFT CENTURY .... -

0T32

01-35
0133

CD5A01
3A2102
CD5A01

R
R

21 1
212
2)3

CALL

CONCAR
A, (YR1 )

CONCAR

(CONVERT

(GET YEAR

(CONVERT . _...._ . ..

01 33
013F
01 40

ED5B2402
B7
CD61 01

R
R

21 4
21 5

21 6

LD
OR
CALL

DE, (JULIAN)

C0NSU1

(JULIAN DAY
(CLEAR CARRY
(CONVERT AND MOVE

0143
01 44
014 7

010800

CD8001

217
21 8
219

EX
LD
CALL

DE,HL
BC,8

LOADSS

(OUTPUT BUFFER ADDRESS TO HL

(COUNT FOR MOVE

(BUMP OVER TIME Al READY IN OUTPUT BUFFER

0} Ak
01 4D

0150

3A2202

CD5D01
3A2602

R
R

220
22 1
222

CALL

A, CMQN1 )
CONSUB
A , ( WK 1 )

(GET MONTH

(CONVERT

(DAY OF WEEK _„ ..._

0153
0156
0J57

CO 5001

C32D00

R
R

223

22 A
225

CALL

XQR

CONSUB

ALEX IT

NOCARY

(CONVERT

(CLEAR ACCUM

(.JUMP TO EXIT _....._

(SET CARRY FLAG (DON'T CALL ED I TM )
(JUMP OVER CLEARING CARRY FLAG

015A

01 5B

37
1 301

226
22 7
228

(

CDN.CAR

SCF
JR

01 50
01 5E
01 60

B7
1600

229
230
231

CONSUB
NOCARY

LD
LD

0,0
E.A

(CLEAR CARRY FLAG (CALL EDITM)

(ZERO MSB FOR CONVERT

fVAIUF TP CONVERT ... __ ._ - _

' 01 61

21 1 B02

232

CQNSU1

HL , BUFF5

(BUFFER CONVERT ADDRESS

199

Model II TRSDOS

OATM
OBJ CODE M STMT SOURCE STATEMENT

12/10/79 — 15*00

PAGE 5

ASM 5.8

" 0j 6<r

01 66
0)67

01 68
016A
01 6B

016C
01 6F
0172

0173
01 74
01 77

0600

233
234
235

LD
PUSH

PUSH

B,0

3E15

236
23 7
238

D49202
2A9301

LD
RST

POP

(CONVERSION PARAMETER

(SAVE ADDRESS

I SAVE FLAGS

A, I 5H

239

240
241

(CONVERT
(SVC

(GET FLAGS

2.3
229301

_AE

242
243
P4 4

CALL NC,EDITM " (EDIT CONVERSION ON NO CARRY
LD HL, .(TABDRS) (TABLE COUNT
_LD C.(HL) (LENGTH TO MOVF

INC

XPR

(TABDRS ) ,HL

0178

0) 79

5.7

0I7A

3E05

0T7C

0J7D

01 7E

245
246
247

LD
LD
LD

248
249

250

8, A
D,A
A f 5

(BUMP

(SAVE ADDRESS

(7FRO ACCOM.

SUB
LD

POP

E, A
HL

(ZERO B
(ZERO
(LENGTH OF CONVERSION BUFFER

(DISPLACEMENT IN CONVERSION BUFFER

(GET VALUE

(FRONT OF CONVERSION B UFFER

017F

0180

110000

251
252
253

LOADSS

ADD
EQU

HL,DE
$

DE,0
$-2

(FIND FIRST DIGIT

(GET BUFFER ADDRESS

0183
0185

03 89

018A

01 88
018C
0.1 8D
.03 8£
01 8F
0190

EDB0
ED538101 R

254
255
256

OUTDSS

EQU

LDIR

257
258
259

02
02
03

02
02

RET
(
TA3LX DEFB

(OUTDSS). DE

(MOVE

(SAVE ADDRESS

260
261
262

DEFB
DEFB
DEFB

0191

0'92

0193

0195

01 AA

0JD1
01 D2
01 03

01D4
01D5
01D6

0107
01D8
01D9

01 DA
01DB
01 DC
01DD

01E1

263
264
265

DEFB
DEFB
DEFB

02
01

266
26 7
268

DEFB
DEFB

(

4D4F4E54

269
270
271

TABDRS
I

NAMDAY

DEFW

DEFM

TABLX

'MONTUEWEDTHUFRISATSUN'

2020204A

00
IF
JC

272
273
274

NAMONT
_l

DEFM

JANFEBMARAPRMAYJUNJULAUGSEP0CTNOVDEC J

275
276
277

FEB

DEFB
DEFB

DEFB

00
31
28

1 F
IE

278
279

280

DEFB
DEFB
DEFB

31
30
31

JE
IF
IF

28 1
282
283

DEFB
DEFB
DEFB

30
31
3^

IE
IF
IE

284
285

286

DEFB
DEFB
DEFB

01DE 3A2I02

287
288
289

30
3i

DEFB

(

LPORNT LD

290

A,(YR1 )

L,A

I NO MONTH
? JAN
(FEB

(MAR
(APR
( MAY

( JUN
(JUL
(AUG

(SEP
(OCT
(NOV

(DEC

(MOVE IT

200

Utility Programs «|i,

LOC

DATM
OBJ CODE M STMT SOURCE STATEMENT

12/1 0/79 — 15:00

PAGE
ASM

01 E2
01 E4
03 E6

01 E9
01 EA
01 EC

0JEE
01 F0
01F2

01F3
01F4
01 F5

01 F6
01 F9

01FB
0JFD
01FE

0204
0206
0209

020A

020B
02 0D

(32idF
02 1 1
021 2

0215
0216
0218

0219
021 A

02 IB

0220

229
022A

22B

022C

022D

022E
0231

^232
0234
0236

FE00
2 004
212002

29 1
292

293

CP
JR
LD

NZ f LP1

HL,CEN1

(SEE IF QUAD OR CEN
(JUMP IF NOT
(CENTURY

0237

6E
26 00

0601

29 4
295
29 6

LD
LD

L , ( HL)
H,0

9,1

I MOVE II

I ZERO MSB

(DIVIDE PARAMETER

0E04
3E17
CF

297
298

299

LD
LD
RST

C,4
A,1 7H
8

1/4

(DIVIDE
I SVC

AF
B9
C9

CDOE01
3E1C

300
301
3^2
303
304
305

XOR

RET

(ZERO ACCU.
(REMAINDER

FIXFEB

CALL
LD

LPORNT
A, 28

(LEAP YEAR ?

(TWENTY EIGHT DAYS OF FEB.

2001

32D301

306
307
308

INC
LD

d2tii

309
310

(

82Q2

0603

31 1

DTBCVT

RET

NZ,NTLPYR

(FEB? ,A

(JUMP IF NOT LEAP
(29 DAYS OF FEB.
(MOD MONTHS TABLE

6,3

(COUNT FOR LEADING ZEROS

3E30
1 1 1B02
1 2

31 2
31 3
31 4

LD
LD
LD

'0*

DF,BUFF5
(DE),A

(LEADING ZEROS
(CONVFRT BUFFER
(LOAD LEADING ZEROS

10FC
0E02

315
31 6
317

INC

DJNZ

LOOP1

C,2

(BUMP
(LOOP

(COUNT

FOR MOVE

EDB0

21 1 B02

31 8
319
320

LDIR
PUSH

HL
HL.

(MOVE

(SAVE POINTER TO

(FRONT OF BUFFER

INFORMATION

3E15

321
322
323

INC
LD

RST

A, 1 5H

(CONVERSION PARAMETER

(CONVERT

(SVC

32 4
32 5
326

POP
RET

(POINTER TO INFORMATION

327
328
329

8UFF5

(
CENI

DEFS

DEFB

(CONVERSION BUFFER

( CENTURY STORE

022)

0222

0223

0224

0000

0226

0227

0000

33%
33 1
332

YR1

MON1
DAY1

DEFB
DEFB
DEFB

00
00
00

(YEAR STORE
(MONTH STORE
(DAY STORE

333

334
335

JULIAN

WK1

JUL1

DEFW
DEFB

DEFW

00
00

(JULIAN
(DAY OF
(JULIAN

DAYS
WEEK
DAYS

IN YEAR

STORE

00
00
00

336
337
338

CEN2

YR2

MQN2

DEFB
DEFB
DEFB

00
00
00

(CENTURY STORE
; YFAR STORE
(MONTH STORE

339
340
341

0AY2

(

CARRY

DEFB

(DAY STORE

(CARRY ACCUMULATOR

CD0202
BB

342
343
344

(
EDIT

CALL
CP

DTBCVT

(CONVERT STRING INFORMATION
(CP MONTH TO ZERO

2851
3E0C

345
346
347

LD
CP

Z, ED I TOR
A,l 2

(QUIT ON ERROR

( 1 2 MONTHS

( MONTHS

38 4C

348

CREDITOR

(QUIT ON ERROR

201

Model II TRSDOS

QATM
OBJ CODE M STMT SOURCE STATEMENT

1 2/1 0/79 — 15100

PAGE 7
ASM 5.8

0239
023A
0230

322282

3E2F

349

350
351

LD
LD
LD

A,E

(M0N1 ) ,A
A, V J

(MONTHS

J SAVE MONTHS

(DATE DELIMITER

023F
0240
02.42

2043

352
353

35 4

CP
JR
INC

CHL)

NZ t £DITOR

(COMPARE TO STRING
(QUIT ON ERROR
(BUMP POINTER

\dZA3
0246
0248

CD0Z02

2030

355
356
357

CALL

DTBCVT
NZ, EDITOR
E

; CONVERT STRING
(QUIT ON ERROR

ICP DAY TO ZERO

0249
0248
024C

283A

3223&2

358
359

360

JR
LD
LD

Z, EDITOR
A,E
(DAY1 ) ,A

;quit on error

IDAY
;SAVE DAY

02 4F
0251
0252

3E2F

2031

361
362
363

LD
CP
JR

A,V

(HL)

NZ, EDITOR

(DATE DELIMITER
ICP TO STRING
(QUIT ON ERROR

0254

02 55
0258

CD 02 02

202B

364
365
366

INC

CALL

DTBCVT
NZ, EDITOR

; BUMP POINTER
(CONVERT STRING
(QUIT ON ERROR

025A
025C

025O

3E0F

3026

367
368
369

CP
JR

A, 15

NC, ED I TOR

( 15TH CENTURY
1 CENTURY

(QUIT ON ERROR

025F
0260
0263

3 22 002
CD 02 02

370
371
372

LD
LD
CALL

A,E

(CEN1 ) , A
DTBCVT

I CENTURY
tSAVE CENTURY
tCONVERT STRING

0266
0268
0269

201D
78
322 1 02

373

374
375

JR
LD
LD

NZ,EDITOR

A,E

( YR1 ) ,A

(QUIT ON ERROR
IYEAR

(STORE YEAR

02 6C
0260
0270

CDF601

3A2202

R
R

376
377
378

PUSH
CALL
LD

FIXFE8
A, (M0N1 )

(SAVE POINTER TO INFORMATION
(FIX FEB.
1 MONTH

0273
0276
02 77

51D-10J

379
380
381

LD
ADD

HL, MONTHS

A,L

L,A

1 MONTHS TABLE

; ADJUST TABLE ADDRESS

(MOVE LSB OF MONTH ADDRESS

02 78
027A

027B

3001

3A2302

382 JR

383 INC

384 OVFLOW LD

NC,OVFLOW

A, (0AY1 )

(JUMP ON NO OVERFLOW
I MSB FOR OVERFLOW
(DAY

02 7E
027F
0280

3D
8E
El

385
386
387

DEC
CP

POP

(HL)

( ADJUST FOR COMPARE
ICOMPARE DAY
(RESTORE POINTER

0281

0283
0284

3002

AF
C9

388
389
390

XOR

RET

NC, ED I TOR
A

(QUIT ON ERROR
(CLEAR FLAGS

0285
0287
0288

3E03

B7
C9

391 EDITOR LD

392 OR

393 RET

A t 3
A

(ERROR ON CALL
(SET FLAG

0289

028B

0604

2\zm2

394 1

395 LOAOR LD

396 LD

B,4
HL,CEN1

(LOOP COUNT

(FRONT OF FIRST DATE rNFO.

028E
0291

112902
C9

397
398
399 (

LD
RET

DE,CEN2

(FRONT OF SECOND DATE INFO.
(RETURN TO SENDER

$2.92
0294

0296

0E05
06 04
3E30

400 EDITM LD

401 LD
4H2 LD

C,5

B,4
A, '0*

(# SIGN. DIGITS COUNT
(MAX SPACES TO INSERT
(LEADING ZERO VALUE

0298
0299
029A

BE
C0
0D

403 EDITM! CR

404 RET

405 DEC

(HL)
NZ

1 ASC-II ZERO ?

(LEAVE IF NOT

(DEC SIGN. DIGIT COUNT

029B

3620

406

(HL) • J

(PUT IN LEADING SPACE

202

Utility Programs

DATM
OBJ CODE M STMT SOURCE STATEMENT

1 2/1 0/79 — 15:00

PAGE 8
ASM 5.8

029D
029E
02A0

02A1
02A4

02EB
02 ED

J0F8

407
408
409

INC

DJNZ

RET

EDITM1

(NEXT BYTE

(LOOP

t RETURN

CO2E02
C22A00

41
41 1
41 2

TWODAT CALL
JP

EDIT

N2» ERROR

;edit input information
;quit ON err or

02A7

3£20

413

02 A9

41 4

02 AA

C22A00

415

02AD

41 6

INC

0a ae

41 7

PUSH

02AF

CD8902

41 8

CALL

A,' '

(HL)

NZ, ERROR

(BLANK

(COMPARE WITH DELIMITER IN STRING

(QUIT ON ERROR

HL
HL
LP A PR

(3UMP INFORMATION POINTER
JSAVE POINTER

;load registers with front OF DATE INFO.

02B2

0104 00

419

BC f 4

0285

EDB0

420

LDIR

0287

421

POP

0288

CD2E02

422

CALL

EDIT

02 BB

C22A00

423

NZ,ERROR

02BE

21 0000

424

HL,00

(LOOP COUNT

I MOVE

(POINTER TO INFORMATION

02C1 222702
02C4 2\2D&2
02C7 36 00

425
426
427

LD
LD
LD

02C9 CD8902~
02CC 1A

02CD 4E

428

429 SWITCH
430

CALL

( JUL1 ) ,HL
HL, CARRY
( HL ) ,

LOADR
A , ( DE )
C , £ HL )

"32UE 77"

02CF 79
02D0 1 2

431
A32
433

LD
LD
LD

(HL) ,A
A,C
(DE) ,A

02D1 23
02D2 13
02D3 1 0F7

434
435
436

INC
INC

DJNZ

HL
DE
SWITCH

02D5 CD8902
02D8 1A
02D9 BE

437 CALL

438 LOW 1ST LD

439 CP

LOADR
A, (DE)
(HL)

02DA

440

INC

02DB

44 1

INC

02DC

DA2A00

R 442

C, ERROR

02DF

20id2

443

NZ,GOOD

02E1

.1 0F5

444
445 (

DJNZ

LOW1 ST

02E3 CD8902
02E6 05
02E7 1 A

446 GOOD CALL LOADR

44 7 DEC B

448 EVENUP LD A , ( DE )

02E8 BE -
02E9 23
02EA 13

449
450
451

203E

10F8

02EF 3A2302~
02F2 5F
02 F3 AF

452

453
454

455
456
457

KJ2F4 57
02F5 2A2702
02F8 ED52

458
459
460

02FA 3006
02FC E5
02FD 21 2D 02

461
462
463

INC

(HL)

JR
DJNZ

N£,COMPAR
EVENUP

LD
XOR

A,(DAY1 )

E t A

LD
LD
SBC

D,A

HL, ( JUL1 )

HL.DE

PUSH

0300

464

DEC

NC.OVERIT

HL, CARRY

(HL)

( EDIT INFORMATION
(QUIT ON ERROR
(ZERO HL

(ZERO JULIAN COUNT
(CARRY ACCUMULATOR
(ZERO IT

(LOAD REGISTERS WITH FRONT OF DATE INFO.

(GET FIRST DATE

(MOVE 1ST DATE _____„— __^_^^_^

(BUMP POINTER
(BUMP POINTER
(LOOP

(LOAD REGISTERS WITH FRONT OP DATE INFO.

(2ND DATE

(1ST DATE ^_^^_____„—

(BUMP
(BUMP
(QUIT ON ERROR

(QUIT LOOKING IF DD02 IS SMALLER DATE
( LOOP

(LOAD REGISTERS WITH FRnNT OF DATE INFO.

(REDUCE COUNT BY ONE

(GET 2ND DATE „___^_

(CP TO NEW DATE (FIRST DATE)

(BUMP

( ADD A MONTH AND UPDATE
(LOOP UNTIL UPDATED

(EARLIER DAY
(MOVE IT
(ZERO A CCU.

(MOVE IT

(TOTAL JULIAN DAYS

(SUBTRACT DAYS

(SKIP IF NO CARRY

(SAVE TOTAL

(CARRY ACCUMULATOR

(ADJUST ACCORDING TO CARRY

203

Model II TRSDOS

LOC

DBJ CODE

STMT

SOURCE

DATM
STATEMENT

12/10/79-

-15:00 PAGE 9
ASM 5.8

0301
$382.
0305

3A2C02

465
466
467

OVERIT

POP

A, ( DAY2)

E,A

1 TOTAL

(THE OTHER DAY
(MOVE IT

0306

0307
0308

EB
3E00

468
469

470

ADO

EX
LD

HL,DE
DE,HL
A,0

; ADD DAYS IN MONTH TH JULIAN TOTAL

; TOTAL TO DE

i 7ER0 ACCU. (KEEP FLAGS)

030A
030O
030F

212002

3001

471
472
473

LD
JR
INC

HL, CARRY

NC .ONOUT
£HL)

; carry ACCUMULATOR

IGO ON IF NO CARRY
;SJMP CARRY ACCUMULATOR

0310
031 1

0314

C22A00
2 1 1B02

R
R

474

475
476

ONOUT

CP
JP
LO

(HL)

N2 f ERROR

HL, BUFFS

(see if any carrys are left
(quit on error
conversion buffer

031 7
0319
031 A

0600

3EI5

477
478
479

LD
PUSH

8,0
HL
A,1 5H

CONVERSION PARAMETER
;SAVE FRONT OF BUFFER
(CONVERT

03 1C

031 D
tf32ti

CD9202

480
481
482

RST

CALL
POP

EDITM

(SVC

(EDIT CONVERSION

(FRONT OF BUFFER

032 1
0324

0327

0.1 0500
COS 001
AF

483
484

485

CALL

XOR

BC f 5

LOADSS

(COUNT

(MOVE TO OUTPUT BUFFER

(GOOD INDICATION

0328
032B

C32D00
CDF6 01

486
48 7
488

(
COMPAR

JP
CALL

ALEXIT
FIXFEB

(END
(FIX FEB.

032E
033 J
id 333

3A2202

1600
5F

489
490
491

LD
LD
LD

A, (M0N1 )

D,0
E,A

(MONTH
(ZERO MSB
(MOVE MONTH

0334
033 7
0338

21DJ01
1 9

492
493
494

ADO

HL, MONTHS

HL,DE

E , ( HL )

(MONTHS TABLE

(FIND MONTH

(GET # OF DAYS IN MONTH

0339

id33C
033D

2A2702

3006

495
496
497

ADD

HL , ( JUL 1 )

HL,DE
NC,FLDW

(TOTAL FOR JULIAN DAYS

(ADD UP TOTAL

(JUMP IF NO OVERFLOW

033F
d3A^d
0343

212D02

498
4 99

500

PUSH

INC

HL, CARRY

(HL)

(SAVE TOTAL

(CARRY ACCUMULATOR

(BUMP CARRY

0344
0345
0348

222702
21 Z2&2.

R
R

501
502
503

FLOW

POP
LD

( JUL1 ) ,HL

HL,M0N1

(TOTAL
(SAVE TOTAL
t MONTH

034B
034C

034D

7E
FE0D

504
505
506

INC

(HL)
A , ( HL )
13

(BUMP MONTH
(MONTH TO ACCU.
( 1 3 MONTHS

034F
0351

0353

3892
D60C
77

507

508
509

JR
SUB

C,GOOO

( HL ) , A

(LOOP ON CARRY
(READJUST
(STORE IT

0354
0357

0358

2 1 2 1 02
34

51
51 1
512

INC

HL, YR1
(HL)
A , ( HL )

(YEAR

(BUMP YEAR
(YEAR TO ACCU.

0359
0358
0350

FE64
3886
0664

51 3

514
515

JR
SUB

1 00

C,GOOD
1 00

t 1 00 YEARS
(LOOP ON CARRY
(READJUST

035F
0360
0363

212002
34

516
51 7
518

LD
LD
INC

( HL ) , A
HL,CEN1
(HL)

(STORE IT
(CENTURY
(BUMP CENTURY

0364

C3E302

519

GOOD

(LOOP

204

Utility Programs

CROSS REFERENCE

SYMBOL VAL M DEFN REFS

1 2/1 0/79 — 1 5:00

PAGE 1

AGAIN
ALEX IT
8UFF5

0037

mzo

02 IB

R
R
R

327

92
225
232

486
313

32k)

476

CARRY
CENl

CEN2

0220
0220
0229

R
R
R

341
329
336

426
1 02
397

463
126

471

1 51

499

210

293 37 1 396 51 7

COMPAR 0328 R

438

452

CONCAR 01 5A R

227

2\ 1

213

CONSU1 0161 R

232

216

CONSUB 01 5D R
DATM 0000 R
DAY1 0223 R

229

332

209 221 223

86 1 09 208 360 384 4 55

OAY2 022C R
DAYOFW 01 0E R
OTSCVT 0202 R

339

195
311

466
193
343

355 365 372

EDIT 022E R 343 48 411
EDITM 0292 R 400 239 48 1
EDITM-1 0298 R 403 408

EOITQR 0285 R 391 345 348 353 356 358 363 366 369 373 388
ERROR 002A R 58 40 43 49 52 106 186 412 415 423 442
4 75

EVENUP 02E7 R 448 453
FEB 0103 R 277 308
FINISH 0080 R 1 09 84

FIXFE8 01T6 R 304 65 377 488

FLOW 0345 R 502 497

GOOD 02E3 R 446 443 507 514 519

87 425 459 495 502

JUL1 0227 R 335

JULDAT 0016 R 48

JULIAN 0224 R 333 1 ?? ISU J2SA

JULT £031 R 65 57 99 107

L08UFF 0099 R 124

LOADR 0289 R 395 4 18 428 437 446

LOAOSS 0180 R 252 196 207 219 484

LO0P1 0209 R 314 316

LOW! ST 02Q8 R 438 444 ___

LP4 01 EA R 295 292

LPORNT 01 DE R 289 1 63 304

MONI 0222 R 331 66 88 I 1 3 1 97 220 350 378 489 503

M0N2 022B R 333

MQNQFY 0123 R 206 204
MONTHS 01 01 R 275 69

1 1 2 379 492

SORE 0331 R 490

NAMDAY 0195 R 271 187
NAMONT 01 AA R 273 198

NEXT1 0080 R 115 121
NEXT 2 0092 R 119 117
NnCARY 01 5F R 2.30 2PB

NOTYET 005A R 87 77

NTLPYR 01.FE R 308 306
nNniJT 0310 R 474 472

OUTDSS 0181 R
QVERIT 0302 R
nVFLOW 02 7B R

254
466
38 4__

461
_18 ?

SWITCH 02CC R
TABORS 01 93 R
TABLX 01 SA R

429
269
259

436

125 240

124 269

243

TWDDAT 02A1 R 4 11

CROSS REFERENCE

SYMBOL VAL M DEFN REFS

1 2/1 0/79 — 15:00

PAGE 1 1

UPDAT3 00OF R
WK1 022h R

YR1 .0221 R

167
334

330

165

180

222

133

212 289 375 510

YR2

022A R 337

205

MODEL II TRSDOS

HERZ50

Set Up for 50 Hz AG power (non-USA users)

D0 HERZ50

starts the utility to change the system for 50 Hz operation, herzso is a DO-file.

This utility is provided for customers in areas where the AC power is 50 rather
than 60 Hz. It should not be used by any other customers.

HERZ50 is a DO-file that makes a few changes in the video display software of
TRSDOS. Only the drive zero diskette is changed. Be sure it is write-enabled
before you start the DO-file. Once the HERZ50 changes are done, they will
remain in effect for that diskette.

To perform the change, type under trsdos ready:
DO HERZ50

The program provides several opportunities for you to abort the process by
pressing E^^ . Pressing any other key during a pause will cause the
program to continue.

Once the change has been made, you will need to reset the system to put the
change into effect. This loads the new video display software into ram.

206

UTILITY PROGRAMS

LPII

Modify Printer Driver for use with

Line Printer II

DG LPII

This DO-file changes the TRSDOS printer driver to make it properly operate the
Radio Shack Line Printer II . It makes a permanent change in the TRSDOS diskette.
The change will take effect when the Computer is reset or started using the modified
TRSDOS.

Sample Use

DO LPII

207

if Model II TRSDOS

PRTBKSP

Modify Printer Driver for Backspacing

DO PRTBKSP

Some printers are capable of backspacing for the purpose of overprinting and other
special applications. For example, the Radio Shack Daisy Wheel printers have this
capability.

The TRSDOS printer driver ordinarily ignores the backspace code (ASCII x w). If
you are using a printer which can handle this code properly, you may want to
modify TRSDOS so that it will send the backspace code to the printer.

To make the modification, execute the DO-file named PRTBKSP. This will make a
permanent change in the TRSDOS diskette. The change will not take effect until the
Computer is started or reset using the modified TRSDOS .

After the modification has been made , TRSDOS will send the backspace character to
the printer, and will decrement the character-in-line count.

Sample Use

DO PRTBKSP

208

Section 4

Technical Information

This chapter explains trsdos on a technical level. You do not need it to

use the Operator Commands, nor do you need it to run basic

applications programs on the Computer. You do need it to write

assembly programs which use System routines. You may also find the

information incidentally useful in programming with basic

Model II TRSDOS

Diskette Organization

Model II uses single-sided, double-density diskettes. Each diskette contains
77 tracks, numbered 0-76.

Each track contains 26 sectors, numbered 1-26. Each sector contains 256
bytes, except for track sectors, which contain 128 bytes. The total capacity
of a diskette is:

(76 * 26 * 256) + (1 * 26 * 128) - 509,184 bytes
Disk Space Available to User

Sector 26 of each track is reserved for System use, giving the user 25 sectors
per track. On System diskettes, 65 tracks are available for the user; on
non-System diskettes, 75 tracks are available.

Details: Track is reserved by the System. Another track (usually track 44) is
reserved by the System for the diskette directory. On Operating System
diskettes, ten additional tracks are used for System files.

Unit of Allocation

The only unit of disk space allocation is the "granule". A TRSDOS granule is
defined as 5 sectors. Therefore the smallest non-empty file consists of 5
sectors; i.e., one granule.

NON-SYSTEM
DISKETTE

TRACKS

GRANULES

SECTORS

BYTES

375' ..;■•
5

■;■■■ 1"

1875
25
5

480,000
6400
1280
256

Table 4.1 Space Available to User

210

Technical Information 1

Disk Files

Methods of File Allocation

Model II provides two ways to allocate disk space for files: Dynamic
Allocation and Pre- Allocation.

Dynamic Allocation

With Dynamic Allocation, the System allocates granules only at the time of
write. For example, when a file is first Opened for output, no space is
allocated. The first space allocation is done at the first write. Additional space
is added as required by subsequent writes.

With dynamically allocated files, unused granules are de-allocated
(recovered) when the file is Closed.

Pre- Allocation

With Pre- Allocation, the file is allocated a specified number of granules when
it is Created. Pre- Allocated files can only be created by the operator command
CREATE.

TRSDOS will dynamically extend (enlarge) a Pre-Allocated file as needed for
subsequent write operation. However, TRSDOS will not de-allocate unused
granules when a pre-allocated file is Closed. The way to reduce the size of a
Pre-Allocated file is to Copy it to a dynamically allocated file and Kill the
Pre-Allocated one.

Record Length

The Model II transfers data to and from diskettes one sector at a time; i.e. , in
256-byte blocks. These are the System's "physical" records.

User records or "logical" records are the buffers of data you wish to transfer
to or from a file. These can be from 1 to 256 bytes long.

The Operating System will automatically "block" your logical records into
physical records which will be transferred to disk, and "de-block" the physical
records into logical records which are used by your program. Therefore your
only concern during file-access is with logical records. You never need to
worry about physical records, sectors, tracks, etc. This is to your benefit,
since physical record lengths and features may change in later TRSDOS
versions, while the concept of logical records will not.

From this point on, the term "record" refers to a "logical record".

211

Model II TRSDOS

Spanning

If the record length is not an even divisor of 256, the records will
automatically be spanned across sectors.

For example, if the record length is 200, Sectors 1 and 2 will look like this:

:<^° B

ONE

SECTOR

Fixed-Length and Variable Length Records

Model II files can have either fixed-length or variable-length records. Files
with fixed-length records will be referred to as FLRs ; files with variable length
records, VLRs.

Record length in an FLR file is set when the file is Opened for the first time. This
length can be any value from 1 to 256 bytes. Once set, the record length in an
FLR cannot be changed, unless the file is being over-written with new data.

Record length in aVLR file is specified in a one-byte length-field at the
beginning of each record. The record-lengths in a VLR file can vary. For
example, the first record in a file might have a length of 32; the second, 17; the
third, 250; etc.

The record-length byte indicates the entire length of the record, including the
length-byte. This can be any value from to 255. A value of 1 can be used, but
it has no meaning.

212

Technical Information

Examples:

A length-byte value of zero indicates that the record contains 255 bytes of

data:

Length

Byte Data

255 bytes of data

A length-byte value of 2 indicates that the record contains 1 byte of data:

Length
Byte

one byte of data

A length-byte value of 16 indicates that the record contains 15 bytes of data:

Length
Byte

Data

15 bytes of data

213

Model II TRSDOS

Record Processing Capabilities

Model II TRSDOS allows both Direct and Sequential file access. Direct
access- sometimes called "random access", but "direct" is more descriptive
— allows you to process any record you specify.

Note: A file can contain up to 65535 records. Records are numbered from
(beginning of file) to 65534. A record number of 65535 indicates the end of file
(EOF). These limits will be changed in a later release of TRSDOS.

Sequential access allows you to process records in sequence: Record N, N+ 1,
N+2, .... With sequential access, you do not specify a record number;
instead, the Operating System accesses the next record following the last
record processed.

For files with fixed length records (FLRs) you can position the current record
pointer to the beginning of the file, end of file, or to any record in the file. In
short, you can use Direct and/or Sequential Access with FLRs at any time
during processing.

For files with variable length records (VLRs) you can only position to the
beginning of the file or to the end of file. You cannot position to any other
record in the file, since the position of interior VLRs cannot be calculated. If
short, you can only use Sequential access with VLRs.

The Direct access routines are Direct-Read and Direct-Write; the Sequential
access routines are Read-Next and Write-Next. Direct access routines always
access the record you specify. Sequential access routines always access the
record following the last record processed. (When the file is first opened,
sequential processing starts with record 0.)

Examples

Assume you have a Fixed Length Record file currently Open. Here are some
typical sequences you can accomplish via the file processing routines.

1. Read and/or write records in the file — in any order

This is done using Direct-Write and Direct-Read routines. You could read
record 5, write at end of file, read record 3, write record 3, etc.

2. Sequential Read (or Write) beginning anywhere in the file.

First you would do a Direct-Read to the record where you want to start
reading or writing. After that, you would do sequential reads or writes until
done.

214

Technical Information

3. Sequential Write starting at end of file.

First do a Direct-Write to the end of the file. Then do sequential writes until
done.

4. Determine the number of records in a file.

First do a Direct-Read to end of file, then use the LOCATE routine to get the
current record number, which now equals number of records +L

Examples with Variable Length Records

Here are examples of ways to read or write to VLR files:

1. Start reading or writing sequentially at first record

Open the file and start reading or writing sequentially until done.

2. Sequential Write starting at end of file

(same process as Example 3 above).

Note: Whenever you write to a VLR, the end of the file is automatically reset
to the last record you write. This means you cannot update a VLR file directly;
you must read in the file and output the updated information to a new VLR
file.

215

Model II TRSDOS

How to Use the Supervisor Calls

Supervisor Calls (SVCs) are Operating System routines available to any user
program. The routines alter certain System functions and conditions; provide
file access; perform I/O to the Keyboard, Video Display, and Printer; and
perform various computations.

All the SVCs leave memory above X'2FFF' untouched. Only those Z-80
registers used to pass parameters from the SVC are altered. All others are
unaffected. However, all the prime registers are used by the System; they are
not restored.

Each SVC is assigned a Function Code. These codes run from through 127.
Only the first 96 are defined by the System; codes 96-127 are available for user
definition.

To specify a given Supervisor Call, your program refers to the SVCs Function
Code.

Calling Procedure

All SVCs are accomplished via the RST 8 instruction.

1 . Load the Function Code for the desired SVC into the A register. Also load
any other registers which are needed by the SVC, as detailed under
"Supervisor Calls."

2. Execute a RST 8 instruction.

3. Upon return from the SVC, the Z flag will be set if the function was
successful. If the Z flag is not set, there was an error. The A register
contains the appropriate error code (except after certain computational
SVCs, which use the A register to return other information).

Examples
Time-Delay

LD
LD
RST

BCiTIMCNT

A? 6

5 DELAY OVER-PROGRAM CONTINUES

Output a line to the Video Display

HL » MSG

&■> 10

LD
LD

C»0DH
A»9

RST

8
N2SG0TERR

LENGTH OF DELAY

FUNCTION CODE 6 = DELAY SVC

JUMP TO SVC
HERE

POINT TO THE MESSAGE

B=CHARACTER COUNT

OCTRL CHAR. TO ADD AT END

CODE 9 = DISPLAY LINE-SVC

JUMP TO SVC

JUMP IF I/O ERROR

IF NO ERROR THEN PROGRAM CONTINUES HERE

216

Technical Information

Get a character from the Keyboard

GETCHAR LD A»4 ; CODE 4

RSI 8 ; JUMP TO < :

JR NZ* GETCHAR ? DO AGAIN

CHARACTER IS IN REGISTER B

GET CHARACTER-SVC
aVC
IF NO CHARACTER

217

Model II TRSDOS

Error Codes and Messages

Register A usually contains a return code after any function call. The Z
flag is set when no error occurred. Exceptions are certain computational
routines, which use the A and F registers to pass back data and status
information.

CODE

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

31
32
33

34:

35
36

MESSAGE

No Error Foijnd

Bad Function Code On SVC Call Or No Function Exists

Character Not Available

Parameter Error On Call

CRC Error During Disk I/O Operation

Disk Sector Not Found

Attempt To Open A File Which Has Not Been Closed

Illegal Disk Change

Disk Drive Not Ready

Invalid Data Provided By Caller

Maximum Of 1 6 Files May Be Open At Once

File Already In Directory

No Drive Available For An Open

Write Attempt To A Read Only File

Write Fault On Disk I/O

Disk is Write Protected

DCB Is Modified And is Unusable

Directory Read Error

Directory Write Error

Improper File Name (fiiespec)

FADReadError

FAD Write Error

FID Read Error

FID Write Error

FiieNotFound

File Access Denied Due To Password Protection

Directory Space Full

Disk Space Full

Attempt To Read Past EOF

Read Attempt Outside Of File Limits

No More Extents Available (.1 6 Maximum)

Program Not Found

Unknown Drive Number (fiiespec)

Disk Space Allocation Cannot Be Made Due To Fragmentation Of Space

Attempt To Use A Non Program File As A Program

Memory Fault During Program Load

Parameter For Open t$ Incorrect : - :

(Continued on next page)

218

Technical Information

CODE

MESSAGE

: ' "jit--.' i

Open Attempt For A File Already Open

I/O Attempt To An Unopen File

SEEK Error

Data Lost During-Disk I/O (Hardware Fault)

Printer Not Ready

Printer Out Of Paper ■

Printer Fault (May Be Turned Off)

Printer Mot Available i-.:.

Not Applicable To VLR Type Files

47,

Requi^ ; vv

Incorrect Command Parameter

49 -:|

Hardware Fault During Disk I/O

50-255

** Unknown Error Code **

219

MODEL II TRSDOS

Supervisor Calls

In this section we will use the following notation:

NOTATION

MEANING

RP = data
n1<R< n'2

(RP) - data

NZ = Error

The register-pair RP contains the data.

The register R contains a value greater than n1

and less than n2
The register-pair RP contains the address of

("points to") the data.
If Z flag is not set, an error occurred.

When a range is not given, any representable number can be used. For
example, a register can contain any value from 0-255.

The contents of this section are:

System Control Supervisor Calls 4/15

Keyboard Supervisor Calls 4/27

Video Display Supervisor Calls 4/31

Line Printer Supervisor Calls 4/45

File Access Supervisor Calls 4/49

Computational Supervisor Calls 4/61

Serial Communications Supervisor Calls 4/75

220

Technical Information

System Control

Supervisor calls described in this section:

FUNCTION

CODE

NAME

PURPOSE

INITIO

Initializes all I/O drivers

SETUSR

Sets up a user-defined SVC

SETBRK

Sets up (BREAK) key processing program

DISKID

Reads a diskette ID

TIMER

Settimerto interrupt program

HLDKEY

Process (HOLD)

JP2DOS

Returns to trsdos (trsdos ready)

DOSCMD

Sends trsdos a command and then
returns to TRSDOS READY

RETCMD

Sends trsdos a command and return
to caller

ERROR

Displays "error number"

ERRMSG

Returns Error Message to Buffer

CLRXIT

I Clear ram and return to trsdos

Table 4.3. System Control Supervisor Calls

INITIO

Initialize I/O (function code 0)

This routine initializes all input/output drivers. It calls all of the other
initialization routines. There are no parameters.

Note: This routine has been done already by the System. Users never need to
call it, except in extreme error conditions.

Error Conditions

A -

Exit Conditions

NZ - Error

A = Error Code

221

Model II TRSDOS

SETUSR

Set User (function code 2)

This routine sets or removes a user vector. This gives you the ability to add SVC
functions. Function codes 96-101 are available for user definition, unless the serial
interface is on (see RS232C). Function codes 102-127 are always available for user
definition.

Once added, such a function can then be called via the RST 8 instruction,
just like the System's SVC routines.

Your routine must reside above X77FF, and should end with a RET
instruction.

To change a previously defined function, you must first remove the old
vector.

Entry Conditions

HL = Entry address of your routine (when C is not equal to 0)

B = Function code to be used, 95< code< 128

C = Set/Reset code. If C=0, remove the vector. Otherwise, add the

vector.
A = 2

Exit Conditions

HL = Removed vector address (when C=0 on entry)

SE TBRK

Set 1 H H DEI Ti f function code 3)

This routine lets you enable the ^^^Hkey by defining a I^ffl3-key processing
program. Whenever the §3133 key is pressed, your processing program takes
over. On entry to the EEB33 processing program, the return address of the
interrupted routine is on the top of the stack and can be returned to with a RETurn
instruction . All Z-80 register contents are unchanged upon entry to the ^^^S
program.

The routine also lets you disable the [I3IE133 key, by removing the address of
the processing program. While ISIS key is enabled, you cannot change
processing programs; you must disable it first.

The C331II3 key processing program must reside above X77FF.

222

Technical Information

See "Handling Programmed Interrupts" for programming information.

Entry Conditions

HL = Address of HUB key processing program. When ^ffi3 is
pressed, control transfers to this address.
If HL = 0, then address of previous processing program is
removed.
A - 3

Exit Conditions

NZ = Error

A = Error Code

(HL) = Address of deleted [133^ key processing program, if HL = on
entry

DISKID
(function code 15)

This routine reads the diskette ID from any or all of drives through 3. (The
diskette ID is assigned by the FORMAT and backup utilities.) This
routine is useful when the program needs to ensure that the Operator has
inserted the proper diskette.

Entry Conditions

B = Drive Select Code. If B = 0, read from drive 0, etc.

B must be one of the following: 0, 1, 2, 3, or 255. If B = 255, then
routine reads from all four drives.

(HL) = Buffer to hold the diskette ID(s).

IfB = 0, 1,2 or 3, then buffer must be 8-bytes long. If B -255, then
buffer must be 32 bytes long. Drive ID will be placed in first 8
bytes, then drive 1, etc.

A = 15

Exit Conditions

The Diskette ID(s) are placed in the buffers pointed to by register-pair HL. If
a drive is not ready, blanks are placed into the buffer.

NZ — Error.

A = Error Code.

223

Model II TRSDOS

TIMER
(function code 25)

This routine lets you start a timer to interrupt a program when time runs out.
Unlike the DELAY routine, TIMER runs concurrently with your program. One
application would be to give an operator a specified number of seconds for
keyboard input, and to interrupt the keyboard input routine if no input was
made within the time limit.

When setting the timer, you tell it how many seconds to count down. TRSDOS
will then continue executing your program, until the timer counts down to
zero or you reset the timer.

This is a "one-shot" timer. When it counts to zero and causes an interrupt, it
automatically shuts off.

See Programming with TRSDOS for information on interrupts.

Entry Conditions

(HL) = Routine to handle interrupt when timer counts to zero
BC = Number of seconds to count down

A- 25

If HL and BC both equal zero, then timer is turned off.

If HL = and BC is not equal to zero, then time count is reset to the value in

BC, and timing continues.

HLDKEY

Process the (HOLD) Key (function code 29)

This routine enables the (HOLD) key pause-function.

Entry Conditions

A-29

B = Function Code

224

Technical Information ~m$rm

Contents of B Result

B - Turn off [HOLD) processor. Pressing (HOLD) will generate

keyboard data xw.
B = 1 Turn on (HOLD) processor. Pressing (HOLD) will not generate keyboard

data; it will be intercepted by TRSDOS.
B> 1 Check for (HOLD) key. If it has been pressed one or more times,

pause until it is pressed again. No matter how many times (HOLD) is
pressed before this function is called, it will be interpreted as a
single keystroke, thus starting the pause.

Exit Conditions

NZ (HOLD) processor is off.

User Notes

To use this function, first turn on the (HOLD) processor by calling the SVC with
B = 1 . Then, when you want to check whether (HOLD) has been pressed, call it again
withB> 1. If (HOLD) has been pressed, the routine will not return until (HOLD) is
pressed a second time.

Returning to the TRSDOS READY command level turns off the (HOLD) processor.
However, you can execute a command without turning off the (HOLD) processor.
See svc's JP2DOS and DOSCMD. Some commands like dir, list, etc. , will reset
the (HOLD) processor.

JP2DOS

Jump to DOS (function 36)

This program simply returns control to the command level (TRSDOS READY).
All Open files are Closed automatically.

Entry Conditions

A= 36

Note: An alternate way to perform this function is to execute an RST0 instruction.
There are no entry conditions for this method.

225

■ r $~>

Model II TRSDOS

DOSCMD

DOS Command (function code 37)

This routine sends TRSDOS a command. After the command is executed,
control returns to TRSDOS (TRSDOS READY). All Open files are closed
automatically.

Entry Conditions

(HL) = TRSDOS command string
B = Length of command string

A = 37

RETCMD

Return after Command (function code 38)

This routine sends TRSDOS an operator command. After completion of the
command, control returns to your program. All Open files are Closed
automatically.

Note: Take care thatTRSDOS doesn't overlay your program while loading the
command file you specified. Most TRSDOS library commands use memory
below X'27FF; a few go up to but not including X'2FFF\ Single-drive, single-
disk copies use all user memory. See Library Commands for details.

Entry Conditions

(HL) = TRSDOS command string

B = Length of command string.

A= 38

Exit Conditions

NZ = Error

A = Error Code

226

Technical Information 1

ERROR

(function code 39)

This routine displays the message ERROR followed by the specified error
code. The message appears at the current cursor position.

Entry Conditions

B = Error Code

A= 39

Exit Conditions

NZ = Error

A = Error Code

ERRMSG

Error Message (function code 52)

This routine returns an 80-byte descriptive error message to the specified
buffer area. (See list of Error Codes and Messages.)

Entry Conditions

B = Error Code corresponding to message

(HL) = 80-byte buffer area in user area (above X77FF)

A- 52

Exit Conditions

NZ = Error

A = Error Code

227

Model II TRSDOS

CLRXIT

Clear User Memory and Jump to TRSDOS

(function code 57)

This routine zeroes user memory and transfers control to TRSDOS READY.

Entry Conditions

A =57

Exit Conditions

None

Keyboard

Supervisor calls described in this section*

FUNCTION
CODE

NAME

PURPOSE

1
4
5
12

KBINIT
KBCHAR
KBLINE
VIDKEY

Clears stored keystrokes.
Gets a character from keyboard.
Gets a line from keyboard.
Display message and get line from KB.

Table 4.4. Keyboard Supervisor Calls

* VIDKEY is described later on under "Video Display."

228

Technical Information

KBINIT

Keyboard Initialize (function code 1)

This routine initializes the keyboard input driver. This call should be made
before you start keyboard input. It clears all previous keystrokes.

Entry Conditions

A =

Exit Conditions

NZ =

Error

A =

Error Code

KBCHAR

Keyboard Character (function code 4)

This routine gets one character from the keyboard. The routine returns
immediately either with or without a character in register B.

The ^^^H key is masked from the user — it will never be returned, since it
is intercepted by the System. If aSETBRK routine is enabled, control passes to
the processing program (see SETBRK) whenever 02333 is pressed.
Otherwise, control pass to trsdos ready.

Entry Conditions

A= 4

Exit Conditions

B = Character found, if any. Only codes within the range [0,127] can be

returned. If no character is returned, B is unchanged.

NZ = No character present

A = Error Code

229

Model II TRSDOS

KBLINE

Keyboard Line (function code 5)

This routine inputs a line from the Keyboard into a buffer, and echoes the line
to the Display, starting at the current cursor position. As each character is
received and displayed, the cursor advances to the next position (Scroll Mode
-see ki Video Display" section on the following pages).
On entry to this routine, the input buffer is filled with periods, and these
periods appear on the Display, indicating the length of the input field for the
operator's convenience.

The line ends when a carriage return is typed or when the input buffer is filled.
A carriage return and erase-to-end-of-screen are always sent to the Display
upon termination of line input; a carriage-return is stored only if the Operator
actually pressed ^^ffl .

Entry Conditions

(HL) =
B -
A =

Start of input buffer.

Maximum number of characters to receive, (X B

Exit Conditions

B = Actual number of characters input, including carriage return

C = if input buffer was filled without carriage return. If line ended

with a carnage return, then C = X'Ofr.

Control codes not listed below are placed in the buffer and represented on the
display with + symbols,

KEY

HEX
CODE

FUNCTION

trnmm

08
0D
17
18
IB

1C
1D

Backspaces the cursor and erases a character.

Terminates line. Clears trailing periods on display but

not in buffer.

Fills remainder of input buffer with blanks, blanks

remainder of Display line.

Fills remainder of input buffer with blanks, blanks to

end of Display.

Reinitializes input function by filling input buffer with

periods and restoring cursor to original position.

Backspaces the cursor to allow editing of line. Does
not erase characters.

Advances the cursor to allow editing of line. Does not
erase characters.

nana

SEES

Table 4.5. Received Control Codes, code < 32

230

Technical Information

Video Display

Supervisor Calls described in this section:

FUNCTION

CODE

NAME

PURPOSE

VDINIT

Initializes Display

VDCHAR

Sends a character, Scroll Mode

VDLINE

Sends a line, Scroll Mode

VDGRAF

Sends characters, Graphics Mode

VDREAD

Reads characters, Graphics Mode

VIDKEY

Displays message, and gets line from KB

CURSOR

Turns cursor on or off

SCROLL

Sets number of lines at top of display
which are not scrolled

VIDRAM

Video/RAM Transfer

Table 4.6. Video Display Supervisor Calls

The Display has two modes of operation — Scroll and Graphics. Cursor
motion and allowable input characters are different in the two modes.

231

odel II TRSDOS

Graphics Mode

In the Graphics Mode, the Display can be thought of as an 80 by 24 matrix, as
illustrated below:

COLUMN

.12... 18... 24.

DISPLAY POSITIONS, GRAPHICS MODE

Note: The Display has two character sizes: 80 characters per line and 40
characters per line. The illustration above shows the 80 character per line
mode.

Each time an acceptable display character is received, it is displayed at the
current cursor position (which is set on entry to the Graphics Mode routines) .
Before displaying the next character, the cursor position is advanced, as
follows:

• If the cursor is to the left of Column 79 , it advances to the next column
position on the same row.

• If the cursor is at Column 79, it wraps around to Column on the next
row.

Cursor motion works the same way in all directions. For example, if the
cursor is at Row 23, Column 40, and the X'FF (graphics-down) code is
received, the cursor wraps around to Row in the same column.

232

Technical Information

Scroll Mode

In the Scroll Mode, the Display can be thought of as a sequence of 1920
display positions, as illustrated below:

DISPLAY POSITIONS, SCROLL MODE

Note: The Display has two character sizes: 80 characters per line and 40
characters per line. The illustration above shows the 80 character per line
mode.

In the scroll mode, each time an acceptable display character is received, it is
displayed at the current cursor position, and the cursor advances to the next
higher numbered position.

When the cursor is on the bottom line and a line-feed or carriage return is
received, or when the bottom line is filled, the entire Display is "scrolled":

1. Line is deleted

2. Lines 1-23 are moved up on one line

3. Line 23 is blanked

4. The cursor is set to the beginning of line 23.

Note: Lines to 22 on the Display can be protected from scrolling via the
SCROLL function call.

233

Model II TRSDOS

VDINIT

Video Initialization (function code 7)

Call this initialization routine once before starting any I/O to the Display. It
blanks the screen and resets the cursor to the top left corner (position in the
Scroll Mode illustration).

Entry Conditions

B = Character size switch. If B=0 then size is set to 40 characters/line.

Otherwise, size is set to 80 characters/line.

C = Normal/Reverse switch. If C = then sets Reverse mode, black on

white background. Otherwise sets Normal mode, white on black
background.

A= 7

Exit Conditions

NZ = Error

A = Error Code

234

Technical Information

VDCHAR

Video Character (function code 8)

This routine outputs a character to the current cursor position. It is a Scroll
Mode routine, as described above.

Control Codes not listed below are ignored.

KEY

HD
(ED

(CTRPfDT
(BACKSPACE)

(CTRD m

(CTRLint)

HEX
CODE

CENTER)

(HEDGD
(CIEDCQD

(cTRppn
(cTRLi rm

(CTlfi Cxl;

rcTRLi m

(cTJDdD

•©'::

02
04
08

0A
OB

0D
0E

OF
14

17
18
19

1B
1G
1D
IE
1F

FUNCTION

Blinking cursor on.

Cursor off.

Turns on steady cursor.

Moves cursor back one position and
blanks the character at that position.

Advances cursor to next tab position . Tab
positions are at 8-character boundaries,
8,16,24,32,..;

Line feed— cursor moves down to next
row, same column position.

Positions cursor to beginning of previous line.

Cursor will not move into the scroll-protected

area

Moves cursor down to beginning of next line.

Turns dual routing on.

Turns dual routing off.

Homes cursor to the first non scroll-protected

position.

Erases to end of line, cursor doesn't move.

Erases to end of screen, cursor doesn't move

Sets Normal Display mode (white on black).
Remains Normal until reset by programmer.

Sets Reverse Display mode (black on white);
Remains Reverse until reset by programmer.
Erases screen and homes cursor (position 0)
Moves cursor back one position.
Moves cursor forward one position.
Sets 80 character/line and clears Display.
Sets 40 character/line and clears Display.

Table 4.7. Received Control Codes, Code<X'20'

235

Model II TRSDOS

Entry Conditions

B = ASCII code for character to be output to the Display; character

codes must be in the range [0,127]

A= 8

Exit Conditions

NZ = Error

A = Error Code

VDLINE

Video Line (function code 9)

This routine writes a buffer of data to the Display, starting at the current
cursor position. It is a Scroll Mode routine.

The buffer should contain ASCII codes in the range [0,127].
Received control codes, code X'20' , are handled as with VDCHAR,

Entry Conditions

(HL) = Beginning of the buffer containing characters to be set to the

Display
B = Number of characters to be sent

C = End of line character. This character will be sent to the Display

after the buffer text

A= 9

Exit Conditions

NZ = Error

A = Error Code

In case of an error:

B = Number of characters not displayed, including the one causing

the error

C = Character causing the error

Upon return, the cursor is always set to the position following the last
character displayed.

236

Technical Information

VDGRAF

Video Graphics (function code 10)

This function displays a buffer of characters, starting at a specified row and
column. It is a Graphics Mode routine (the cursor "wraps" the Display).

Displayable Characters

This routine lets you display the 32 graphics characters (and their reverse
images). The codes are numbered from through X'lF\ and are pictured in
the Operator's Manual. Codes X'2(r through X7F are displayed as standard
ASCII characters.

In addition, several special control codes are available:

HEX
CODE

FB
FC

FE
FF

FUNCTION

Sets Normal (white on black) mode. Cursor does not advance.

Mode reverts to previous state after completion of vdgraf

call.

Sets Reverse (black on white) mode. Cursor does not advance.

Mode reverts to previous state after completion of vdgraf

call.

Homes cursor (Row 0, Column 0).

Moves cursor back one space. Col. = Col-1 . When column equals 0,

cursor wraps to Col. 79 on the preceding row.

Moves cursor forward one space. Col. = Col. + 1 . When column

equals 79, cursor wraps to Col. on the next row down.

Moves cursor up one row. Row = Row-1 . "Wraps" to Row 23 when

Row = 0.

Moves cursor down one row. Row = Row + 1 . "Wraps" up to Row

when Row ^23.

Table 4.8. Special Graphics Control Codes

At exit, the cursor is always set to the Graphics position immediately after the
last character displayed. If the Buffer length was zero, the cursor is set to
position specified inBC registers.

237

f Model II TRSDOS

Entry Conditions

B = Row on screen to start displaying the buffer, B<24. If B>23, then

B modulo 24* is used as row position.

C = Column on screen to start displaying the buffer. In 80 character/

line mode, C < 80. For C> 79, C modulo 80 is used as column
position.

In 40 character/line mode, C < 40. For C > 39, C modulo 40 is used
as column position.

D = Length of buffer, in range [0,255]

(HL) - Beginning of text buffer. The buffer should contain codes below
XW or the special control codes above XT8\ Any value outside
these ranges will cause an error.

A- 10

Exit Conditions

NZ => Error (invalid character sent)
A = Error Code

* Modulo- A cyclical counting system. For modulus n, x modulo n is the
integer remainder after division of x by n. For example, 85 modulo 80-5.

238

Technical Information

VDREAD Video Read
(funtion code 11)

This routine reads characters from the Video Display into a specified buffer.
It is a Graphics Mode routine; when it reads past the last column, it wraps
back to column 1 on the next row. When it reads past column 79 on row 23, it
wraps back to row 0, column 0.

Reverse (black on white) mode characters are read in as ASCII codes just like
their Normal counterparts; Reverse mode is indicated when the most
significant bit (bit 7) is set.

This routine can also be used just to locate the cursor (see below).

Entry Conditions

B = Row on screen where read starts, B < 24

If B > 23, then B mod 24 is used as row position.

C = Column on screen where read starts

In 80 character/line mode, C < 80
For C >79, C mod 80 is used as column position.
In 40 character/line mode, C < 40
For C > 39, C mod 40 is used as column position.

D = Length of buffer, in range [0,255]. If D = 0, then B and C are

ignored. Current cursor position will be returned as row, column in
BC register pair.

(HL) =

Beginning of text buffer

A =

Exit Conditions

BC =

Current cursor position, B =

exit is the same as at entry

NZ =

Error

A =

Error Code

row, C = column. CURSOR position at
- VDREAD does not change it.

239

Model II TRSDOS

VIDKEY
(function code 12)

This routine sends a prompting message to the Display and then waits for a
line from the Keyboard. It is a Scroll Mode routine, combining the functions
of VDLINE and KBLINE.

The routine writes the specified text buffer to the Display, starting at the
current cursor position. The text buffer must contain codes<X'80\ Refer to
VDLINE for a list of Received Control Codes and other details.

After the Video write, the cursor will be positioned immediately after the last
character displayed. (To move it to another position, control codes can be
placed at the end of the text buffer.)

Next, the routine gets a line from the Keyboard.

Note: Before starting the line input, all previously stored keystrokes are
cleared.

Refer to KBLINE for a list of Received Control Codes and other details.

Entry Conditions

(HL) = Beginning of text buffer containing display message

B = Number of characters to be displayed, B in the range [0,255]

C = Length of Keyboard Input field, C in the range [0,255]

(DE) = Beginning of text buffer where Keyboard input will be stored

A= 12

Exit Conditions

NZ = Error (illegal value in display buffer)

A = Error Code

If Z is set (no error), then registers B and C contain:

B = Number of characters input from Keyboard, including carriage

return, if any

C = Keyboard Line termination. If C = 0, then input buffer was filled.

Otherwise C = control character that terminated the line (carriage
return).

240

Technical Information

If Z is not set (error), the registers B and C contain:

B = Number of characters not displayed, including the one causing the

error

C = Character causing the error

CURSOR

(function code 26)

This routine turns the blinking cursor on or off. The System still keeps track of
the current cursor position, whether it is on or off.

Entry Conditions

B = Function Switch. If B = then cursor will be turned off. If B<>0

then cursor will be turned on.

A= 26

SCROLL
(function code 27)

This routine lets you protect a portion of the Display from scrolling. From to
22 lines at the top of the Display can be protected; when scrolling occurs, only
lines below the protected area will be changed.

Entry Conditions

B = Number of lines to be protected, in range [0,22].

A= 27

241

Model II TRSDOS

VIDRAM

Transfer Video Display to RAM or Vice-Versa

(function code 94)

This command allows a screenful of graphics and/or text to be copied from a RAM
buffer to the video display, or vice-versa. The programmer must be aware of the
current display mode — 80 characters/line or 40 characters/line .

Every possible data byte is treated as a displayable character. There are no cursor
position or other control codes . The following table summarizes the character/code
relationships for this routine:

Hex Code Display Character

00- 1 F Normal Graphics
20-7F Normal ASCII Text
80-9F Reversed Graphics
AO-FF Reversed ASCII Text

Entry Conditions

A =94

B = Function Code

If B = 0, copy from RAM to video

IfB^ 0, copy from video to RAM
(HL) = RAMBuffer. Startof buffer must be above X'2800'; end of buffermustbe

below xtooo'.

If video is in 80 cpl mode , buffer must be 80 * 24 = 1 920 bytes long .

If video is in 40 cpl mode, buffer must be 40 * 24 = 960 bytes long.

Exit Conditions

The cursor position is unchanged by this SVC.

242

Technical Information

Line Printer

Supervisor Calls described in this section:

FUNCTION

CODE

NAME

PURPOSE

PRINIT

Initializes the Line Printer Driver.

PRCHAR

Sends a character to the Printer.

PRUNE

Sends a line to the Printer.

PRCTRL

Controls printer operations.

Table 4.9. Line Printer Supervisor Calls

PRINIT

Printer Initialization (function code 17)

This routine initializes the printer driver only. It does not advance the printer paper,
and it does not check the printer status. It will operate whether or not the printer is
on-line.

Entry Conditions

A = 17

B = Page length

C = Printed lines per page

D = Maximum number of characters per line

IfB = C =*= 0,TRSDOS will not do any automatic top of form. However, it will
translate a form feed code X'OC or XOB 1 into the correct number of carriage returns
or line feeds to get the paper to the top of the next form .

IfB — 0,C must also equal O. Similarly, if C = Othen B must also equal O. In such
a case, form feeds X'OC and vertical tabs X k OB' are not translated but are sent
directly to the printer.

If D = O, TRSDOS will not translate tabs X W as one to eight spaces. It will send the
character directly to the printer. It will continue to update the character count, with
tab XW counting as a single character.

243

f Model II TRSDOS

Exit Conditions

The current character count and current line count are set to zero. TRSDOS assumes
that the paper is already at the top of form when this routine is called.

' ' Dummy ' ' and 'Transparent ' ' printer modes are both returned to ' ' Normal ' ' .
(See SVC PRCTRL. ) The serial/parallel and auto linefeed options are unchanged by

PR I NIT.

User Notes

1 . TRSDOS maintains current line-on-page and current character-in-line counts
regardless of which initialization settings are used. See SVC PRCTRL for further
details on these counts.

2. The printer need not be ready when prinit is called.

3. Whenever TRSDOS is started (reset or power-on), this initialization is done
automatically, with the following parameters:

Parameter (PRINIT register) Value

Page Length (B = ) 66

Printed lines/page (C = ) 60

Max. characters/line (D= ) 132

The other options set during initialization are:
Parallel printer
Non-auto line feed
Non-dummy
Non-transparent

244

Technical Information miii

PRCHAR

Print Character (function code 18)

This routine sends one character to the Printer.

Note: Most printers do not print until their buffer is filled or a carriage
return is received.

Entry Conditions

B = ASCII code for character to send

A= 18

Exit Conditions

NZ =
A =

Notes

Error
Error Code

While the serial printer option is selected, allowing printer output to Channel B ,
two INPUT characters are recognized from Channel B . These will affect all serial
printer output operations:

ASCII
Name

DC3,"CTRL-S"
DC1/CTRL-Q"

Hex

Code

13
11

Result

Pause printing
Resume printing

Certain codes are normally intercepted by TRSDOS and are not sent directly to the
printer. There are several ways to override some or all of these character
translations. See SVC prinit and SVC PRCTRL.

Table of Intercepted Codes

ASCII
Name

Tab

Vertical
Tab

Form
Feed

Carriage
Return

Hex

Code Result to Printer

09 From one to eight spaces are sent to provide a tab function .

OB Same as form feed below .

Special 8D

TRSDOS sends enough carriage returns or line feeds to the printer
to advance the paper to the next top of form .

When the current line is empty (no characters printed since the
last carriage return or line feed) , this is translated as a line feed to
allow correct operation of Radio Shack printers. In the auto line
feed mode, X'OA' is sent after every X'OD'.

TRSDOS sends a carriage return to the printer. In the auto line feed
mode, using this code allows you to send a carriage return
without a line feed.

245

Model II TRSDOS

PRLINE

Print Line (function code 19)

This routine sends a line to the Printer. The line can include control characters as
well as printable data. See PRCHAR for a list of intercepted codes.

See PRCHAR for addition notes on serial output and on special character handling.

Entry Conditions

(HL) = Start of text buffer containing data and controls to send to Printer

B = Length of buffer (number of characters to send)

C = Control Character (any character) to send after last character in

buffer

A- 19

Exit Conditions

NZ - Error

A = Error Code

PRCTRL

Control Printer Operations (function code 95)

This routine lets you select various printer options and check the status of
printer-related functions.

Note: If you are using the spooler's capture function, the captured data is sent
directly to the capture-file — regardless of what control settings are selected. If you
are using the spooler's print function, the printed data will be interpreted according
to the currently selected control settings . See SPOOL for details.

Entry Conditions

A -95

C = Used with certain options (see option list below)

B = Option code:

246

Technical Information

Contents of B

(Decimal) Option (details are given later)

Get printer status only (see Exit Conditions)

1 Select serial printer driver (you must initialize channel B first)

2 Select parallel printer driver

3 Reset current line count; register C contains new count

4 Reset current character count on current line; register C contains the
new count

5 Begin transparent mode

6 End transparent mode

7 Begin dummy mode

8 End dummy mode

9 Begin auto line-feed after carriage return
10 End auto line-feed after carriage return

Exit Conditions

NZ = Error Occurred.

Z = SVC completed without error.

B = Page Length

C = Maximum number of lines to be printed on each page

D = Maximum number of characters to be printed on each line

E = ASCII "P" or ' ' S " (Indicates which printer option , Parallel or

Serial Printer, is selected.)

H = Number of characters printed on current line since last carriage return

L = Number of lines printed since last top of form

Explanation of Options

Serial/Parallel Printer Option

While the serial printer option is selected, allowing printer output to Channel B ,
two input characters are recognized from Channel B . These will affect all serial
printer output operations:

ASCII

Hex

Name

Code

Result

DC3/CTRL-S"

Pause printing

DC1/CTRL-Q"

Resume printing

Line count/Character Count

TRSDOS maintains a single line counter and a single character counter. These are
updated for either serial or parallel printing . TRSDOS does not maintain separate
counters for serial and parallel printing.

247

Model II TRSDOS

Transparent Mode

The transparent mode overrides all data translation. All data bytes go directly to the
printer. There is no examination of content. The line and character counts are not
updated.

Normally, TRSDOS "intercepts" certain control characters and interprets them.
This allows TRSDOS to provide printer-related features which may not be available
from the printer.

For example, tabs (XW) are intercepted so that TRSDOS can send the appropriate
number of spaces to provide the tab function. Form feeds (X'OC or X l OB') are
intercepted so that TRSDOS may advance the paper to the top of the next form.

Code translation may be overridden individually by special settings of the printer
initialization values. See SVC PRINIT for details.

Dummy Output Mode

The dummy mode "throws away" all printer output and returns with a ' 'good" (Z
flag set) return code. During dummy mode operation, the line count and character
count remain unchanged.

Auto Line Feed

Normally, the TRSDOS printer driver does not print line feeds after carriage returns.
This is because most Radio Shack printers do an automatic line-feed after every
carriage return.

If your printer does not perform automatic line-feeds after carriage returns, you
may enable the TRSDOS auto line-feed function.

While the function is enabled, a line-feed will be output after each carriage return.
This is true in all modes including the transparent mode.

Note: In the auto line-feed mode, you may send a carriage return with no linefeed
by outputting the code X'8D' . If the printer is capable of overprinting, this latter
code will return the carriage without advancing the paper.

Precedence of Options

The following table shows which options have priority over others . Options are

listed in order of descending priority.

Spool Capture-Mode (See SPOOL command)

Dummy Mode

Auto Line-Feed after Carriage Return

Transparent Mode

Normal Mode

248

Technical Information

User Notes

1 . If you are using the spooler' s capture function , the captured data is sent directly
to the capture-file — regardless of what printer control settings are selected. If
you are using the spooler's print function, the printed data will be interpreted
according to the currently selected forms control settings. See SPOOL for details.

2. You can operate with two printers, by switching between the serial and parallel
output modes. One printer can use the automatic control features of TRSDOS
(auto form feed, etc.), while the other printer is controlled by the program. This
is necessary since only one set of control counters is maintained.

One possible approach: Select the transparent operation before you switch to the
serial printer and select normal operation before you switch to the parallel printer.
That way, the line and character count will remain accurate for the parallel printer.
It will be up to your program to control the serial printer.

File Access

Supervisor calls described in this section:

Function

Code

Name

Function

33 '"."._;

LOCATE

Returns the current record number.

READNX

Gets next record (Sequential Access).

35 -.■...'■■■-.

DiRRD

Reads specified record (Direct Access) .

OPEN

Sets up access to new or existing file.

:. 41

KILL

Deletes the file from the directory.

Terminates access to an Open file.

WRITNX

Writes next record (Sequential Access).

DIRWR

Writes specified record (Direct Access).

RENAME

Renames a file.

WILD

Compares a file specification
with a wild-card specification.

RAMDIR

Getsdirectory information into ram.

FILPTR

Gets pointers of an open file.

Table. 4.10. File Access Calls

249

Model II TRSDOS

LOCATE

(function code 33)

This function returns the number of the current record, i.e., the number of
the last record accessed. You can use this call only with Fixed Length Record
files.

Entry Conditions

(DE) = Data Control Block for currently Open file (see OPEN )
HL = Reserved for use in later versions of TRSDOS
A= 33

Exit Conditions

BC = Current Record Number

NZ = Error

A = Error Code

READNX

Internet Archive Audio

Featured

Top

Images

Featured

Top

Software

Featured

Top

Texts

Featured

Top

Video

Featured

Top

Mobile Apps

Browser Extensions

Archive-It Subscription

Save Page Now

Full text of "TRS-80 Manual: Model 2 Disk Operating System Reference Manual (19xx)(Tandy)"

See other formats